fix(#1237): let ps/install work on a roster-v2 fleet, and refuse add/remove honestly

On a roster-v2 fleet, `ps`, `install`, `install-systemd`, `add` and `remove` all failed in the v1 parser. The consequence was that a greenfield v2 box could never get its unit templates placed, so nothing downstream could start. The read-only commands get a narrow version-agnostic view of the roster (version, socket name, holder session, and per agent name/alias/runtime). This is deliberately not a v2 -> v1 downshift. A downshifted FleetRoster would be accepted by generateAgentEnvValues, which would make a third writer of fleet/agents/<name>.env.generated through the v1 mapping and break the #791 single-SSOT invariant that projectRosterV2AgentGeneratedEnv is documented to hold. The view is too small to write a roster or an env file back from, so that misuse is unavailable rather than merely discouraged. So on a v2 roster `install` places the tool files and the unit templates, enables the units, and writes no generated env at all. Env belongs to `apply` and `regen`, both already v2-native. That change alone would have traded an init-time failure for a boot-time one. `install` enables mosaic-agent@<name>.service (WantedBy=default.target) without starting it, so a reboot between `install` and the first `apply` would run ExecStart against an absent env file and fail every seat unit, further from its cause. The unit template now carries ConditionPathExists=%h/.config/mosaic/fleet/agents/%i.env.generated which skips an enabled-but-unconfigured unit cleanly and starts it on the next start once the reconciler has written env. On v1 it is a no-op, since v1 `install` writes env itself. Found in review by scooby. `add` and `remove` are not routed to `create` and `delete`. They are different operations: the v1 pair edits the roster and drives systemd, the v2 pair is documented as changing desired state without runtime actions. `add` also collects four fields where a v2 agent requires eleven, so routing it would mean inventing an operator's provider, alias, reasoning and tool policy. On v2 both now fail with the real two-step sequence instead. Tests: 8 new, 7 of which are red before this change. Includes the greenfield case scooby asked for — `ps` on a fresh v2 install with nothing running is rc=0 and lists every agent stopped, since that is the command an operator runs to find out why there is no seat. Note for anyone verifying this: a correct fix here shows `install` rc=0 and `start` rc=0 and still no live seat. #1240 (tmux absent) is upstream, #1241 (start reports lifecycle-complete over dead panes) and the missing agent runtime are downstream. A dead pane after this change is not a regression here. Refs #1237, #791, #1240, #1241
2026-08-15 23:24:24 -05:00
parent 7a6fb024b4
commit 463745e314
3 changed files with 379 additions and 8 deletions
@@ -0,0 +1,265 @@
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { registerFleetCommand, type CommandResult, type CommandRunner } from './fleet.js';
+
+/**
+ * #1237: the v1-only commands (`ps`, `install`, `install-systemd`, `add`,
+ * `remove`) rejected a roster-v2 fleet outright, so a greenfield v2 box could
+ * never get its units placed. These tests pin the three behaviours that fix
+ * gives it, and the two it deliberately does NOT give it.
+ *
+ * The load-bearing negative is that `install` on v2 writes no generated env:
+ * the reconciler owns that file through projectRosterV2AgentGeneratedEnv, and a
+ * second writer here — necessarily through the v1 mapping — is exactly the
+ * drift the #791 single-SSOT invariant exists to prevent.
+ */
+
+const rosterV2 = `
+version: 2
+generation: 4
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: /srv/mosaic
+  runtime: pi
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: coder0
+    alias: Coder 0
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: high
+    tool_policy: code
+    working_directory: /srv/mosaic
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+  - name: coder1
+    alias: Coder 1
+    class: code
+    runtime: pi
+    provider: openai
+    model: gpt-5.6-sol
+    reasoning: medium
+    tool_policy: code
+    working_directory: /srv/other
+    persistent_persona: false
+    reset_between_tasks: true
+    lifecycle:
+      enabled: true
+      desired_state: stopped
+    launch:
+      yolo: true
+`;
+
+let tempHome: string | undefined;
+const savedHome = process.env.HOME;
+const savedMosaicHome = process.env.MOSAIC_HOME;
+
+afterEach(async (): Promise<void> => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+  if (savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = savedHome;
+  if (savedMosaicHome === undefined) delete process.env.MOSAIC_HOME;
+  else process.env.MOSAIC_HOME = savedMosaicHome;
+  if (tempHome) await rm(tempHome, { recursive: true, force: true });
+  tempHome = undefined;
+});
+
+/**
+ * A HOME with a roster-v2 fleet and nothing else — the greenfield shape, before
+ * anything has been installed, applied or started.
+ */
+async function v2Home(): Promise<string> {
+  tempHome = await mkdtemp(join(tmpdir(), 'mosaic-fleet-v2-dispatch-'));
+  process.env.HOME = tempHome;
+  delete process.env.MOSAIC_HOME;
+  const mosaicHome = join(tempHome, '.config', 'mosaic');
+  for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
+    await mkdir(join(mosaicHome, directory), { recursive: true, mode: 0o700 });
+  }
+  await writeFile(join(mosaicHome, 'fleet', 'roster.yaml'), rosterV2, { mode: 0o600 });
+  await writeFile(join(mosaicHome, 'fleet', 'roles', 'code.md'), '`class: code`\n\n# code\n', {
+    mode: 0o600,
+  });
+  return mosaicHome;
+}
+
+/**
+ * Stands in for a box where nothing is running: every systemctl and tmux probe
+ * fails the way it does before the holder has ever started. `ps` must survive
+ * this — it is the command an operator reaches for to find out *why* there is
+ * no seat, so it has to report the emptiness rather than fail on it.
+ */
+const greenfieldRunner: CommandRunner = async (command): Promise<CommandResult> => {
+  if (command === 'tmux') {
+    return { stdout: '', stderr: 'no server running on /tmp/tmux-1000/mosaic-fleet', exitCode: 1 };
+  }
+  return { stdout: '', stderr: '', exitCode: 1 };
+};
+
+function program(runner: CommandRunner = greenfieldRunner): Command {
+  const result = new Command();
+  result.exitOverride();
+  registerFleetCommand(result, { runner, frameworkRoot: resolve(process.cwd(), 'framework') });
+  return result;
+}
+
+function capture(): string[] {
+  const lines: string[] = [];
+  vi.spyOn(console, 'log').mockImplementation((value: string): void => {
+    lines.push(value);
+  });
+  return lines;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('mosaic fleet ps — roster v2', (): void => {
+  it('lists every v2 agent on a greenfield box with nothing running, and does not throw', async (): Promise<void> => {
+    await v2Home();
+    const lines = capture();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'ps', '--json']),
+    ).resolves.toBeDefined();
+
+    const rows = JSON.parse(lines.join('\n')) as {
+      name: string;
+      runtime: string;
+      alias?: string;
+      paneAlive: boolean;
+      source: string;
+    }[];
+    expect(rows.map((row) => row.name).sort()).toEqual(['coder0', 'coder1']);
+    // The v2 roster's per-agent fields must survive the read model, not be
+    // flattened into defaults.
+    expect(rows.every((row) => row.runtime === 'pi')).toBe(true);
+    expect(rows.find((row) => row.name === 'coder0')?.alias).toBe('Coder 0');
+    // Nothing is running, and that is a report, not an error.
+    expect(rows.every((row) => row.paneAlive === false)).toBe(true);
+    expect(rows.every((row) => row.source === 'roster')).toBe(true);
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+});
+
+describe('mosaic fleet install — roster v2', (): void => {
+  it('places the tool files and unit templates', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    capture();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']),
+    ).resolves.toBeDefined();
+
+    // Units live in the systemd user dir, not under the Mosaic home.
+    const systemdUserDir = join(tempHome!, '.config', 'systemd', 'user');
+    for (const unit of [
+      'mosaic-tmux-holder.service',
+      '[email protected]',
+      '[email protected]',
+    ]) {
+      expect(await exists(join(systemdUserDir, unit))).toBe(true);
+    }
+    const launcher = join(mosaicHome, 'tools', 'fleet', 'start-agent-session.sh');
+    expect(await exists(launcher)).toBe(true);
+    expect((await stat(launcher)).mode & 0o777).toBe(0o755);
+  });
+
+  it('writes NO generated env — that file belongs to the reconciler (#791)', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    capture();
+
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    const agentDir = join(mosaicHome, 'fleet', 'agents');
+    expect(await readdir(agentDir)).toEqual([]);
+  });
+
+  it('tells the operator which command does own the env', async (): Promise<void> => {
+    await v2Home();
+    const lines = capture();
+
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    expect(lines.join('\n')).toContain('mosaic fleet apply');
+  });
+});
+
+describe('[email protected]', (): void => {
+  it('will not attempt a seat before the reconciler has written its env', async (): Promise<void> => {
+    // The pairing that makes "install writes no env" safe: install enables the
+    // unit (WantedBy=default.target) but does not start it, so without this
+    // condition a reboot between `install` and the first `apply` would run
+    // ExecStart against an absent env file and fail every seat unit.
+    const unit = await readFile(
+      resolve(process.cwd(), 'framework', 'systemd', 'user', '[email protected]'),
+      'utf8',
+    );
+    expect(unit).toContain('ConditionPathExists=%h/.config/mosaic/fleet/agents/%i.env.generated');
+  });
+});
+
+describe('mosaic fleet add / remove — roster v2', (): void => {
+  it('add refuses, and names the two-step v2 sequence instead of inventing defaults', async (): Promise<void> => {
+    await v2Home();
+
+    await expect(
+      program().parseAsync([
+        'node',
+        'mosaic',
+        'fleet',
+        'add',
+        'coder2',
+        '--runtime',
+        'pi',
+        '--class',
+        'code',
+      ]),
+    ).rejects.toThrow(/mosaic fleet create[\s\S]*mosaic fleet apply/);
+  });
+
+  it('remove refuses, and names delete plus apply', async (): Promise<void> => {
+    await v2Home();
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
+    ).rejects.toThrow(/mosaic fleet delete coder1[\s\S]*mosaic fleet apply/);
+  });
+
+  // Note: this one passes on the unmodified tree too — there `remove` throws in
+  // the v1 parser, before it can touch anything. It is a regression guard on the
+  // ordering of the new guard clause, not evidence that the fix works.
+  it('refuses BEFORE mutating the roster', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+    const before = await readFile(rosterPath, 'utf8');
+
+    await expect(
+      program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
+    ).rejects.toThrow();
+
+    expect(await readFile(rosterPath, 'utf8')).toBe(before);
+  });
+});