fix(fleet): resolve-then-validate symlink guard + framework helper resolution (#1380) (#1383)

Co-authored-by: code-be-01 <[email protected]>

packages/mosaic/src/fleet/comms-onboarding.spec.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import {
   chmodSync,
   mkdtempSync,
@@ -16,6 +16,7 @@ import {
   renderPeerReach,
   readFleetCommsBlock,
   resolveCommsBlock,
+  resolveFleetIdentity,
   resolvePeerCommand,
   renderToolsContractStatus,
 } from './comms-onboarding.js';
@@ -61,6 +62,68 @@ describe('shared fleet roster v1 resolver', () => {
     });
   });
 
+  // stack#1380 verification unblock: the fleet's own roster-v2 tooling writes
+  // the v1 body plus a generation fence and seat lifecycle/launch envelopes.
+  // The parser tolerates exactly that envelope (validated, opaque to comms).
+  const V2_ROSTER = [
+    'version: 2',
+    'generation: 8',
+    'transport: tmux',
+    'tmux:',
+    '  socket_name: mosaic-fleet',
+    'defaults:',
+    '  working_directory: ~/.mosaic',
+    '  runtime: claude',
+    'agents:',
+    '  - name: orch-01',
+    '    runtime: claude',
+    '    class: orchestrator',
+    '    model: opus',
+    '    reasoning: high',
+    '    lifecycle:',
+    '      enabled: true',
+    '      desired_state: running',
+    '    launch:',
+    '      yolo: false',
+    '',
+  ].join('\n');
+
+  it('accepts the roster-v2 envelope (generation + lifecycle/launch) on the v1 body', () => {
+    const resolved = parseFleetRosterV1(V2_ROSTER, 'yaml');
+    expect(resolved.tmux.socketName).toBe('mosaic-fleet');
+    expect(resolved.agents[0]?.name).toBe('orch-01');
+  });
+
+  it('rejects a non-integer generation', () => {
+    expect(() =>
+      parseFleetRosterV1(V2_ROSTER.replace('generation: 8', 'generation: eight'), 'yaml'),
+    ).toThrow(/generation must be a non-negative integer/);
+  });
+
+  it('rejects an invalid lifecycle desired_state', () => {
+    expect(() =>
+      parseFleetRosterV1(
+        V2_ROSTER.replace('desired_state: running', 'desired_state: paused'),
+        'yaml',
+      ),
+    ).toThrow(/desired_state must be running\|stopped/);
+  });
+
+  it('rejects unknown fields inside the lifecycle envelope', () => {
+    expect(() =>
+      parseFleetRosterV1(
+        V2_ROSTER.replace('      enabled: true', '      enabled: true\n      surprise: 1'),
+        'yaml',
+      ),
+    ).toThrow(/lifecycle has unknown field/);
+  });
+
+  it('rejects a non-boolean launch.yolo', () => {
+    expect(() =>
+      parseFleetRosterV1(V2_ROSTER.replace('yolo: false', 'yolo: sometimes'), 'yaml'),
+    ).toThrow(/launch\.yolo must be a boolean/);
+  });
+
   it('rejects unknown fields instead of leniently constructing a second roster view', () => {
     expect(() => parseFleetRosterV1(`${ROSTER}\nunknown: value\n`, 'yaml')).toThrow(
       /unknown field/i,
@@ -493,6 +556,11 @@ describe('resolvePeerCommand', () => {
 describe('readFleetCommsBlock — spawned-agent context', () => {
   let home: string;
   beforeEach(() => {
+    // Hermetic helper fallback (stack#1380): the resolver probes
+    // $HOME/.config/mosaic when mosaicHome itself carries no helper — point
+    // HOME at a sandbox parent so tests never see the real host install.
+    vi.stubEnv('HOME', mkdtempSync(join(tmpdir(), 'mosaic-homeless-')));
+    vi.stubEnv('MOSAIC_HOME', '');
     home = mkdtempSync(join(tmpdir(), 'mosaic-comms-'));
     mkdirSync(join(home, 'fleet'), { recursive: true });
     mkdirSync(join(home, 'tools', 'tmux'), { recursive: true });
@@ -501,7 +569,10 @@ describe('readFleetCommsBlock — spawned-agent context', () => {
     writeFileSync(helper, '#!/bin/sh\n');
     chmodSync(helper, 0o755);
   });
-  afterEach(() => rmSync(home, { recursive: true, force: true }));
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    rmSync(home, { recursive: true, force: true });
+  });
 
   it('uses the authoritative self host and global socket from the shared roster resolver', () => {
     const result = readFleetCommsBlock(home, 'enhancer', 'process-host-must-not-win');
@@ -564,23 +635,27 @@ describe('readFleetCommsBlock — spawned-agent context', () => {
       },
     ],
     [
-      'symlink',
+      'symlink escaping the install home',
       () => {
         const helper = join(home, 'tools', 'tmux', 'agent-send.sh');
         rmSync(helper);
-        writeFileSync(join(home, 'real-send.sh'), '#!/bin/sh\n');
-        symlinkSync(join(home, 'real-send.sh'), helper);
+        const outside = mkdtempSync(join(tmpdir(), 'mosaic-helper-outside-'));
+        writeFileSync(join(outside, 'real-send.sh'), '#!/bin/sh\n', { mode: 0o755 });
+        symlinkSync(join(outside, 'real-send.sh'), helper);
       },
     ],
     ['non-executable', () => chmodSync(join(home, 'tools', 'tmux', 'agent-send.sh'), 0o644)],
-  ])('fails closed for a %s helper with deterministic repair guidance', (_case, mutate) => {
-    mutate();
-    const result = readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
-    expect(result.ok).toBe(false);
-    expect(result.output).toBe('');
-    expect(result.error).toContain('mosaic update --repair-tools');
-    expect(result.error).toContain('no active context or session was rewritten');
-  });
+  ])(
+    'fails closed for a %s helper with deterministic guidance (no forbidden remedy)',
+    (_case, mutate) => {
+      mutate();
+      const result = readFleetCommsBlock(home, 'enhancer', 'w-jarvis');
+      expect(result.ok).toBe(false);
+      expect(result.output).toBe('');
+      expect(result.error).not.toContain('--repair-tools'); // stack#1380 M5a
+      expect(result.error).toContain('no active context or session was rewritten');
+    },
+  );
 
   it('does not rewrite the roster while resolving context', () => {
     const path = join(home, 'fleet', 'roster.yaml');
@@ -603,11 +678,11 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
   });
   afterEach(() => rmSync(home, { recursive: true, force: true }));
 
-  it('uses the supported repair command when installed TOOLS.md is missing', () => {
+  it('names operator-verified recovery instead of a forbidden remedy when installed TOOLS.md is missing', () => {
     const status = renderToolsContractStatus(home);
-    expect(status).toContain('mosaic update --repair-tools');
-    expect(status).not.toContain('--reseed');
     expect(status).toContain('authorized operator');
+    expect(status).not.toContain('--repair-tools'); // stack#1380 M5a
+    expect(status).not.toContain('--reseed');
   });
 
   it('reports stale preserved content without rewriting it', () => {
@@ -616,8 +691,8 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
     writeFileSync(path, stale);
     const status = renderToolsContractStatus(home);
     expect(status).toContain('fleet-comms-contract: 1');
-    expect(status).toContain('digest-qualified backup');
-    expect(status).toContain('mosaic update --repair-tools');
+    expect(status).toContain('authorized operator');
+    expect(status).not.toContain('--repair-tools'); // stack#1380 M5a
     expect(status).toContain('active context was not rewritten');
     expect(readFileSync(path, 'utf8')).toBe(stale);
   });
@@ -648,7 +723,7 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
     expect(renderToolsContractStatus(home)).not.toBe('');
   });
 
-  it('treats installed TOOLS.md symlinks as stale without following or rewriting them', () => {
+  it('reads an installed TOOLS.md symlink whose validated target diverges (stack#1380 resolve-then-validate)', () => {
     const external = join(home, 'external-tools.md');
     const externalContent = '# external\n<!-- fleet-comms-contract: 1 -->\n';
     writeFileSync(external, externalContent);
@@ -656,24 +731,23 @@ describe('renderToolsContractStatus — non-mutating install drift', () => {
 
     const status = renderToolsContractStatus(home);
 
-    expect(status).toContain('unavailable');
-    expect(status).toContain('mosaic update --repair-tools');
+    expect(status).toContain('does not byte-match');
     expect(readFileSync(external, 'utf8')).toBe(externalContent);
   });
 
-  it('treats source TOOLS.md symlinks as unavailable without following them', () => {
-    const external = join(home, 'external-source.md');
+  it('treats a source TOOLS.md symlink escaping the install home as unavailable', () => {
+    const outside = mkdtempSync(join(tmpdir(), 'mosaic-source-outside-'));
     const content = '# authoritative tools\n<!-- fleet-comms-contract: 1 -->\n';
-    writeFileSync(external, content);
+    writeFileSync(join(outside, 'external-source.md'), content);
     rmSync(join(home, 'defaults', 'TOOLS.md'));
-    symlinkSync(external, join(home, 'defaults', 'TOOLS.md'));
+    symlinkSync(join(outside, 'external-source.md'), join(home, 'defaults', 'TOOLS.md'));
     writeFileSync(join(home, 'TOOLS.md'), content);
 
     const status = renderToolsContractStatus(home);
 
     expect(status).toContain('source contract');
     expect(status).toContain('unavailable');
-    expect(readFileSync(external, 'utf8')).toBe(content);
+    expect(readFileSync(join(outside, 'external-source.md'), 'utf8')).toBe(content);
   });
 
   it('accepts byte-equal bounded source and installed contracts', () => {
@@ -730,3 +804,91 @@ describe('resolveCommsBlock — mosaic agent comms-block', () => {
     expect(result.error).toContain('requires');
   });
 });
+
+describe('resolveFleetIdentity — stack#1380 split-home layouts', () => {
+  // Brain-shaped mosaicHome (fleet state, NO tools/tmux) + framework config
+  // home carrying the helper, roster unified by the framework-created symlink
+  // <configHome>/fleet/roster.yaml -> <brain>/fleet/roster.yaml. This is the
+  // host layout that was down; all probes are POSITIONAL per the #1380
+  // verification protocol (an object arg proves nothing — M5b). HOME is
+  // stubbed so the config-default fallback stays inside the sandbox.
+  let brain: string;
+  let configHome: string;
+
+  beforeEach(() => {
+    const parent = mkdtempSync(join(tmpdir(), 'mosaic-i1380-parent-'));
+    brain = join(parent, 'brain');
+    // Framework home at the stubbed DEFAULT location so the fallback derives
+    // exactly as in production ($HOME/.config/mosaic), not by coincidence.
+    configHome = join(parent, 'home', '.config', 'mosaic');
+    vi.stubEnv('HOME', join(parent, 'home'));
+    vi.stubEnv('MOSAIC_HOME', '');
+    mkdirSync(join(brain, 'fleet'), { recursive: true });
+    writeFileSync(join(brain, 'fleet', 'roster.yaml'), ROSTER, { mode: 0o600 });
+    mkdirSync(join(configHome, 'fleet'), { recursive: true });
+    symlinkSync(join(brain, 'fleet', 'roster.yaml'), join(configHome, 'fleet', 'roster.yaml'));
+    mkdirSync(join(configHome, 'tools', 'tmux'), { recursive: true });
+    writeFileSync(join(configHome, 'tools', 'tmux', 'agent-send.sh'), '#!/bin/sh\n', {
+      mode: 0o755,
+    });
+    process.env['MOSAIC_BRAIN_HOME'] = brain;
+  });
+
+  afterEach(() => {
+    delete process.env['MOSAIC_BRAIN_HOME'];
+    vi.unstubAllEnvs();
+    rmSync(join(brain, '..'), { recursive: true, force: true });
+  });
+
+  it('resolves a member through the roster symlink under the config home', () => {
+    const result = resolveFleetIdentity(configHome, 'orchestrator', 'w-jarvis');
+    expect(result.ok).toBe(true);
+    expect(result.identity?.member.name).toBe('orchestrator');
+    expect(result.identity?.agentSendPath).toBe(join(configHome, 'tools', 'tmux', 'agent-send.sh'));
+  });
+
+  it('resolves a member when mosaicHome is the brain (helper found under the framework home)', () => {
+    const result = resolveFleetIdentity(brain, 'enhancer', 'w-jarvis');
+    expect(result.ok).toBe(true);
+    expect(result.identity?.member.name).toBe('enhancer');
+    expect(result.identity?.agentSendPath).toBe(join(configHome, 'tools', 'tmux', 'agent-send.sh'));
+  });
+
+  it('no-name control stays a quiet no-op', () => {
+    expect(resolveFleetIdentity(configHome, undefined, 'w-jarvis')).toEqual({ ok: true });
+    expect(resolveFleetIdentity(brain, undefined, 'w-jarvis')).toEqual({ ok: true });
+  });
+
+  it('a nonce name fails naming membership, not the symlink or the helper', () => {
+    const result = resolveFleetIdentity(configHome, 'nonce-' + Date.now(), 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).not.toContain('symbolic link');
+    expect(result.error).not.toContain('helper');
+    expect(result.error).toContain('nonce-');
+  });
+
+  it('a non-member failure names membership, not the symlink (protocol control)', () => {
+    const result = resolveFleetIdentity(configHome, 'jarvis', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).not.toContain('symbolic link');
+    expect(result.error).not.toContain('helper is unavailable');
+    expect(result.error).toContain('orchestrator'); // known-member listing
+  });
+
+  it('names every searched framework home when the helper is missing everywhere', () => {
+    rmSync(join(configHome, 'tools'), { recursive: true, force: true });
+    const result = resolveFleetIdentity(brain, 'orchestrator', 'w-jarvis');
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('agent-send.sh');
+    expect(result.error).toContain(join(brain, 'tools', 'tmux', 'agent-send.sh'));
+    expect(result.error).not.toContain('--repair-tools');
+  });
+
+  it('readFleetCommsBlock composes the full contract on the split-home layout', () => {
+    const result = readFleetCommsBlock(configHome, 'orchestrator', 'w-jarvis');
+    expect(result.ok).toBe(true);
+    expect(result.output).toContain(
+      'Helper: `' + join(configHome, 'tools', 'tmux', 'agent-send.sh'),
+    );
+  });
+});