fix(macp): fail-closed typed gate states — no placeholder/empty-command passes (#1275)

RI-N2 / SDLC-D-035. Every GateResult now carries a typed status
discriminator (passed|failed|simulated|waiting|capability_failure);
passed:true remains true only for really-executed, really-green gates.

- ci-pipeline without a CI provider → capability_failure (MACP_NO_CI_PIPELINE),
  never the placeholder pass
- empty-command gate → capability_failure (MACP_NO_COMMAND / MACP_NO_REVIEWER),
  and runGates no longer silently skips it
- manual gate type waits (MACP_AUTHORITY_REQUIRED) — neither pass nor fail
- explicit simulation only (simulate option / --simulate): typed simulated
  results can never make the aggregate passed (RunGatesResult.state)
- CLI stubs (tasks list, submit, events tail) exit nonzero with typed
  MACP_NOT_IMPLEMENTED; macp gate is now wired to runGates with --simulate
- legacy __tests__/gate-runner.test.ts consolidated into src/gate-runner.spec.ts
  (root eslint project service does not cover packages/macp/__tests__)

packages/macp/__tests__/gate-runner.test.ts

@@ -1,253 +0,0 @@
-import { mkdirSync, readFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { randomUUID } from 'node:crypto';
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { normalizeGate, countAIFindings, runGate, runGates } from '../src/gate-runner.js';
-
-function makeTmpDir(): string {
-  const dir = join(tmpdir(), `macp-gate-${randomUUID()}`);
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-describe('normalizeGate', () => {
-  it('normalizes a string to mechanical gate', () => {
-    expect(normalizeGate('echo test')).toEqual({
-      command: 'echo test',
-      type: 'mechanical',
-      fail_on: 'blocker',
-    });
-  });
-
-  it('normalizes an object gate with defaults', () => {
-    expect(normalizeGate({ command: 'lint' })).toEqual({
-      command: 'lint',
-      type: 'mechanical',
-      fail_on: 'blocker',
-    });
-  });
-
-  it('preserves explicit type and fail_on', () => {
-    expect(normalizeGate({ command: 'review', type: 'ai-review', fail_on: 'any' })).toEqual({
-      command: 'review',
-      type: 'ai-review',
-      fail_on: 'any',
-    });
-  });
-
-  it('handles non-string/non-object input', () => {
-    expect(normalizeGate(42)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
-    expect(normalizeGate(null)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
-  });
-});
-
-describe('countAIFindings', () => {
-  it('returns zeros for non-object', () => {
-    expect(countAIFindings(null)).toEqual({ blockers: 0, total: 0 });
-    expect(countAIFindings('string')).toEqual({ blockers: 0, total: 0 });
-    expect(countAIFindings([])).toEqual({ blockers: 0, total: 0 });
-  });
-
-  it('counts from stats block', () => {
-    const output = { stats: { blockers: 2, should_fix: 3, suggestions: 1 } };
-    expect(countAIFindings(output)).toEqual({ blockers: 2, total: 6 });
-  });
-
-  it('counts from findings array when stats has no blockers', () => {
-    const output = {
-      stats: { blockers: 0 },
-      findings: [{ severity: 'blocker' }, { severity: 'warning' }, { severity: 'blocker' }],
-    };
-    expect(countAIFindings(output)).toEqual({ blockers: 2, total: 3 });
-  });
-
-  it('uses stats blockers over findings array when stats has blockers', () => {
-    const output = {
-      stats: { blockers: 5 },
-      findings: [{ severity: 'blocker' }, { severity: 'warning' }],
-    };
-    // stats.blockers = 5, total from stats = 5+0+0 = 5, findings not used for total since stats total is non-zero
-    expect(countAIFindings(output)).toEqual({ blockers: 5, total: 5 });
-  });
-
-  it('counts findings length as total when stats has zero total', () => {
-    const output = {
-      findings: [{ severity: 'warning' }, { severity: 'info' }],
-    };
-    expect(countAIFindings(output)).toEqual({ blockers: 0, total: 2 });
-  });
-});
-
-describe('runGate', () => {
-  let tmp: string;
-  let logPath: string;
-
-  beforeEach(() => {
-    tmp = makeTmpDir();
-    logPath = join(tmp, 'gate.log');
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it('passes mechanical gate on exit 0', () => {
-    const result = runGate('echo hello', tmp, logPath, 30);
-    expect(result.passed).toBe(true);
-    expect(result.exit_code).toBe(0);
-    expect(result.type).toBe('mechanical');
-    expect(result.output).toContain('hello');
-  });
-
-  it('fails mechanical gate on non-zero exit', () => {
-    const result = runGate('exit 1', tmp, logPath, 30);
-    expect(result.passed).toBe(false);
-    expect(result.exit_code).toBe(1);
-  });
-
-  it('ci-pipeline always passes', () => {
-    const result = runGate({ command: 'anything', type: 'ci-pipeline' }, tmp, logPath, 30);
-    expect(result.passed).toBe(true);
-    expect(result.type).toBe('ci-pipeline');
-    expect(result.output).toBe('CI pipeline gate placeholder');
-  });
-
-  it('empty command passes', () => {
-    const result = runGate({ command: '' }, tmp, logPath, 30);
-    expect(result.passed).toBe(true);
-  });
-
-  it('ai-review gate parses JSON output', () => {
-    const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
-    const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
-    expect(result.passed).toBe(true);
-    expect(result.blockers).toBe(0);
-    expect(result.findings).toBe(1);
-  });
-
-  it('ai-review gate fails on blockers', () => {
-    const json = JSON.stringify({ stats: { blockers: 2 } });
-    const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
-    expect(result.passed).toBe(false);
-    expect(result.blockers).toBe(2);
-  });
-
-  it('ai-review gate with fail_on=any fails on any findings', () => {
-    const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
-    const result = runGate(
-      { command: `echo '${json}'`, type: 'ai-review', fail_on: 'any' },
-      tmp,
-      logPath,
-      30,
-    );
-    expect(result.passed).toBe(false);
-    expect(result.fail_on).toBe('any');
-  });
-
-  it('ai-review gate fails on invalid JSON output', () => {
-    const result = runGate({ command: 'echo "not json"', type: 'ai-review' }, tmp, logPath, 30);
-    expect(result.passed).toBe(false);
-    expect(result.parse_error).toBeDefined();
-  });
-
-  it('writes to log file', () => {
-    runGate('echo logged', tmp, logPath, 30);
-    const log = readFileSync(logPath, 'utf-8');
-    expect(log).toContain('COMMAND: echo logged');
-    expect(log).toContain('logged');
-    expect(log).toContain('EXIT:');
-  });
-});
-
-describe('runGates', () => {
-  let tmp: string;
-  let logPath: string;
-  let eventsPath: string;
-
-  beforeEach(() => {
-    tmp = makeTmpDir();
-    logPath = join(tmp, 'gates.log');
-    eventsPath = join(tmp, 'events.ndjson');
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it('runs multiple gates and returns results', () => {
-    const { allPassed, gateResults } = runGates(
-      ['echo one', 'echo two'],
-      tmp,
-      logPath,
-      30,
-      eventsPath,
-      'task-1',
-    );
-    expect(allPassed).toBe(true);
-    expect(gateResults).toHaveLength(2);
-  });
-
-  it('reports failure when any gate fails', () => {
-    const { allPassed, gateResults } = runGates(
-      ['echo ok', 'exit 1'],
-      tmp,
-      logPath,
-      30,
-      eventsPath,
-      'task-2',
-    );
-    expect(allPassed).toBe(false);
-    expect(gateResults[0]!.passed).toBe(true);
-    expect(gateResults[1]!.passed).toBe(false);
-  });
-
-  it('emits events for each gate', () => {
-    runGates(['echo test'], tmp, logPath, 30, eventsPath, 'task-3');
-    const events = readFileSync(eventsPath, 'utf-8')
-      .trim()
-      .split('\n')
-      .map((l) => JSON.parse(l));
-    expect(events).toHaveLength(2); // started + passed
-    expect(events[0].event_type).toBe('rail.check.started');
-    expect(events[1].event_type).toBe('rail.check.passed');
-  });
-
-  it('skips gates with empty command (non ci-pipeline)', () => {
-    const { gateResults } = runGates(
-      [{ command: '', type: 'mechanical' }, 'echo real'],
-      tmp,
-      logPath,
-      30,
-      eventsPath,
-      'task-4',
-    );
-    expect(gateResults).toHaveLength(1);
-  });
-
-  it('does not skip ci-pipeline even with empty command', () => {
-    const { gateResults } = runGates(
-      [{ command: '', type: 'ci-pipeline' }],
-      tmp,
-      logPath,
-      30,
-      eventsPath,
-      'task-5',
-    );
-    expect(gateResults).toHaveLength(1);
-    expect(gateResults[0]!.passed).toBe(true);
-  });
-
-  it('emits failed event with correct message', () => {
-    runGates(['exit 42'], tmp, logPath, 30, eventsPath, 'task-6');
-    const events = readFileSync(eventsPath, 'utf-8')
-      .trim()
-      .split('\n')
-      .map((l) => JSON.parse(l));
-    const failEvent = events.find(
-      (e: Record<string, unknown>) => e.event_type === 'rail.check.failed',
-    );
-    expect(failEvent).toBeDefined();
-    expect(failEvent.message).toContain('Gate failed (');
-  });
-});

packages/macp/src/cli.spec.ts

@@ -1,5 +1,8 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
 import { Command } from 'commander';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { registerMacpCommand } from './cli.js';
 
 describe('registerMacpCommand', () => {
@@ -75,3 +78,162 @@ describe('registerMacpCommand', () => {
     expect(topLevel).toContain('events');
   });
 });
+
+/**
+ * RI-N2 fail-closed CLI behavior: an unimplemented capability is a failure,
+ * never a success. Every stub exits nonzero with a typed message, and the
+ * implemented `macp gate` mirrors the typed gate-runner states.
+ */
+describe('registerMacpCommand fail-closed (RI-N2)', () => {
+  let tmpDir: string;
+
+  function buildProgram(): Command {
+    const program = new Command();
+    program.exitOverride();
+    program.configureOutput({ writeErr: () => {} });
+    registerMacpCommand(program);
+    return program;
+  }
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'macp-cli-failclosed-'));
+    process.exitCode = 0;
+  });
+
+  afterEach(() => {
+    process.exitCode = 0;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('macp tasks list exits nonzero (unimplemented capability)', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['macp', 'tasks', 'list'], { from: 'user' });
+    expect(process.exitCode).not.toBe(0);
+  });
+
+  it('macp submit exits nonzero with a typed MACP_NOT_IMPLEMENTED message', async () => {
+    const program = buildProgram();
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      await program.parseAsync(['macp', 'submit', 'spec.json'], { from: 'user' });
+      expect(process.exitCode).not.toBe(0);
+      const errText = errSpy.mock.calls.map((c) => String(c[0])).join('\n');
+      expect(errText).toContain('MACP_NOT_IMPLEMENTED');
+    } finally {
+      errSpy.mockRestore();
+    }
+  });
+
+  it('macp events tail exits nonzero (unimplemented capability)', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['macp', 'events', 'tail'], { from: 'user' });
+    expect(process.exitCode).not.toBe(0);
+  });
+
+  it('macp gate runs a green inline command and exits 0', async () => {
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        'macp',
+        'gate',
+        'exit 0',
+        '--cwd',
+        tmpDir,
+        '--log',
+        path.join(tmpDir, 'g.log'),
+        '--timeout',
+        '10',
+      ],
+      { from: 'user' },
+    );
+    expect(process.exitCode).toBe(0);
+  });
+
+  it('macp gate exits nonzero on a failing command', async () => {
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        'macp',
+        'gate',
+        'exit 9',
+        '--cwd',
+        tmpDir,
+        '--log',
+        path.join(tmpDir, 'g.log'),
+        '--timeout',
+        '10',
+      ],
+      { from: 'user' },
+    );
+    expect(process.exitCode).not.toBe(0);
+  });
+
+  it('macp gate with an unimplemented ci-pipeline capability exits nonzero', async () => {
+    const program = buildProgram();
+    const specPath = path.join(tmpDir, 'gates.json');
+    fs.writeFileSync(specPath, JSON.stringify([{ type: 'ci-pipeline' }]));
+    await program.parseAsync(
+      [
+        'macp',
+        'gate',
+        specPath,
+        '--cwd',
+        tmpDir,
+        '--log',
+        path.join(tmpDir, 'g.log'),
+        '--timeout',
+        '10',
+      ],
+      { from: 'user' },
+    );
+    expect(process.exitCode).not.toBe(0);
+  });
+
+  it('macp gate --simulate completes (exit 0) but reports simulated results', async () => {
+    const program = buildProgram();
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await program.parseAsync(
+        [
+          'macp',
+          'gate',
+          'exit 0',
+          '--simulate',
+          '--cwd',
+          tmpDir,
+          '--log',
+          path.join(tmpDir, 'g.log'),
+          '--timeout',
+          '10',
+        ],
+        { from: 'user' },
+      );
+      // completes only because the caller explicitly asked to simulate
+      expect(process.exitCode).toBe(0);
+      const outText = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+      expect(outText).toContain('simulated');
+      expect(outText).toContain('SIMULATED');
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it('macp gate with an empty spec exits nonzero with a typed error', async () => {
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        'macp',
+        'gate',
+        '   ',
+        '--cwd',
+        tmpDir,
+        '--log',
+        path.join(tmpDir, 'g.log'),
+        '--timeout',
+        '10',
+      ],
+      { from: 'user' },
+    );
+    expect(process.exitCode).not.toBe(0);
+  });
+});

packages/macp/src/cli.ts

@@ -1,5 +1,73 @@
+import { existsSync, readFileSync } from 'node:fs';
+
 import type { Command } from 'commander';
 
+import { runGates } from './gate-runner.js';
+import { MACPCapabilityError, type MacpErrorCode } from './errors.js';
+
+/**
+ * Load gates from a spec: an existing file (JSON gates array, a JSON object
+ * with `quality_gates`, a JSON gate object, or one command per line) or an
+ * inline command string. Fails closed with a typed capability error when the
+ * spec contains no executable gate definition.
+ */
+function loadGateSpec(spec: string): unknown[] {
+  if (existsSync(spec)) {
+    const raw = readFileSync(spec, 'utf-8');
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (Array.isArray(parsed)) {
+        if (parsed.length === 0) {
+          throw new MACPCapabilityError(
+            'MACP_NO_COMMAND',
+            'gate-spec',
+            `gate spec file '${spec}' contains an empty gates array`,
+          );
+        }
+        return parsed;
+      }
+      if (typeof parsed === 'object' && parsed !== null) {
+        const obj = parsed as Record<string, unknown>;
+        if (Array.isArray(obj['quality_gates'])) {
+          return obj['quality_gates'];
+        }
+        return [parsed];
+      }
+      throw new MACPCapabilityError(
+        'MACP_NO_COMMAND',
+        'gate-spec',
+        `gate spec file '${spec}' parsed to ${typeof parsed} — expected a gates array, a task with quality_gates, or a gate object`,
+      );
+    } catch (exc) {
+      if (exc instanceof MACPCapabilityError) throw exc;
+      // Not JSON — treat each non-empty line as a command gate.
+      const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+      if (lines.length > 0) return lines;
+      throw new MACPCapabilityError(
+        'MACP_NO_COMMAND',
+        'gate-spec',
+        `gate spec file '${spec}' contains no gates`,
+      );
+    }
+  }
+  if (spec.trim().length > 0) return [spec];
+  throw new MACPCapabilityError('MACP_NO_COMMAND', 'gate-spec', 'gate spec is empty');
+}
+
+/** Print a typed not-implemented failure and exit nonzero (RI-N2 fail-closed). */
+function notImplemented(subcommand: string, capability: string, hint: string): void {
+  const err = new MACPCapabilityError(
+    'MACP_NOT_IMPLEMENTED',
+    capability,
+    `${subcommand} is not implemented in @mosaicstack/macp yet (${capability} capability absent) — ${hint}`,
+  );
+  console.error(`[macp] ${subcommand}: ${err.message} [${err.code}]`);
+  process.exitCode = 1;
+}
+
 /**
  * Register macp subcommands on an existing Commander program.
  * This avoids cross-package Commander version mismatches by using the
@@ -24,15 +92,14 @@ export function registerMacpCommand(parent: Command): void {
       'Filter by task type (coding|deploy|research|review|documentation|infrastructure)',
     )
     .action((opts: { status?: string; type?: string }) => {
-      // not yet wired — task persistence layer is not present in @mosaicstack/macp
+      // unimplemented capability — a failure, never a success (RI-N2)
-      console.log('[macp] tasks list: not yet wired — use macp package programmatically');
       if (opts.status) {
         console.log(`  status filter: ${opts.status}`);
       }
       if (opts.type) {
         console.log(`  type filter: ${opts.type}`);
       }
-      process.exitCode = 0;
+      notImplemented('tasks list', 'task-persistence', 'use the macp package programmatically');
     });
 
   // ─── submit ──────────────────────────────────────────────────────────────
@@ -41,12 +108,11 @@ export function registerMacpCommand(parent: Command): void {
     .command('submit <path>')
     .description('Submit a task from a JSON/YAML spec file')
     .action((specPath: string) => {
-      // not yet wired — task submission requires a running MACP server
+      // unimplemented capability — a failure, never a success (RI-N2)
-      console.log('[macp] submit: not yet wired — use macp package programmatically');
       console.log(`  spec path: ${specPath}`);
       console.log('  task id:   (unavailable — no MACP server connected)');
       console.log('  status:    (unavailable — no MACP server connected)');
-      process.exitCode = 0;
+      notImplemented('submit', 'macp-server', 'use the macp package programmatically');
     });
 
   // ─── gate ────────────────────────────────────────────────────────────────
@@ -58,16 +124,58 @@ export function registerMacpCommand(parent: Command): void {
     .option('--cwd <path>', 'Working directory for gate execution', process.cwd())
     .option('--log <path>', 'Path to write gate log output', '/tmp/macp-gate.log')
     .option('--timeout <seconds>', 'Gate timeout in seconds', '60')
-    .action((spec: string, opts: { failOn: string; cwd: string; log: string; timeout: string }) => {
+    .option(
-      // not yet wired — gate execution requires a task context and event sink
+      '--simulate',
-      console.log('[macp] gate: not yet wired — use macp package programmatically');
+      'Simulate gates instead of executing them; results are typed simulated and never satisfy a check',
-      console.log(`  spec:     ${spec}`);
+    )
-      console.log(`  fail-on:  ${opts.failOn}`);
+    .action(
-      console.log(`  cwd:      ${opts.cwd}`);
+      (
-      console.log(`  log:      ${opts.log}`);
+        spec: string,
-      console.log(`  timeout:  ${opts.timeout}s`);
+        opts: { failOn: string; cwd: string; log: string; timeout: string; simulate?: boolean },
-      process.exitCode = 0;
+      ) => {
-    });
+        let gates: unknown[];
+        try {
+          gates = loadGateSpec(spec);
+        } catch (exc) {
+          if (exc instanceof MACPCapabilityError) {
+            console.error(`[macp] gate: ${exc.message} [${exc.code}]`);
+          } else {
+            console.error(`[macp] gate: ${String(exc)}`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+
+        const timeoutSec = Number.parseInt(opts.timeout, 10) || 60;
+        const eventsPath = `${opts.log}.events.ndjson`;
+        const { state, gateResults } = runGates(
+          gates,
+          opts.cwd,
+          opts.log,
+          timeoutSec,
+          eventsPath,
+          'macp-cli-gate',
+          {
+            simulate: opts.simulate,
+          },
+        );
+
+        for (const r of gateResults) {
+          const label = r.command || r.type;
+          const reason = r.reason ? ` — ${r.reason}` : '';
+          console.log(`[macp] gate ${r.status}: ${label}${reason}`);
+        }
+        if (opts.simulate) {
+          console.log(
+            '[macp] SIMULATED run — every result is typed simulated and can never satisfy a gate, dependency, or release check',
+          );
+        }
+
+        // Simulated runs may complete (exit 0) only because the caller
+        // explicitly passed --simulate; the typed state stays 'simulated'.
+        process.exitCode = state === 'passed' || state === 'simulated' ? 0 : 1;
+      },
+    );
 
   // ─── events ──────────────────────────────────────────────────────────────
 
@@ -79,14 +187,16 @@ export function registerMacpCommand(parent: Command): void {
     .option('--file <path>', 'Path to the MACP events NDJSON file')
     .option('--follow', 'Follow the file for new events (like tail -f)')
     .action((opts: { file?: string; follow?: boolean }) => {
-      // not yet wired — event streaming requires a live event source
+      // unimplemented capability — a failure, never a success (RI-N2)
-      console.log('[macp] events tail: not yet wired — use macp package programmatically');
       if (opts.file) {
         console.log(`  file:   ${opts.file}`);
       }
       if (opts.follow) {
         console.log('  mode:   follow');
       }
-      process.exitCode = 0;
+      notImplemented('events tail', 'event-source', 'use the macp package programmatically');
     });
 }
+
+// Re-export so CLI consumers can surface typed capability codes.
+export type { MacpErrorCode };

packages/macp/src/errors.ts

@@ -0,0 +1,35 @@
+/** Typed error code from the closed MACP_ERROR_CODES set. */
+export type MacpErrorCode = (typeof MACP_ERROR_CODES)[number];
+/**
+ * Typed fail-closed capability errors (RI-N2, SDLC-D-035).
+ *
+ * MACP must fail closed when a required capability (executor, reviewer,
+ * command, CI provider, human authority) is absent. These typed codes mirror
+ * the Forge failure vocabulary (FORGE_NO_*) so both packages speak the same
+ * language: an unimplemented capability is a failure, never a stub success.
+ */
+
+/** Closed set of typed MACP capability error codes. */
+export const MACP_ERROR_CODES = [
+  'MACP_NOT_IMPLEMENTED',
+  'MACP_NO_COMMAND',
+  'MACP_NO_REVIEWER',
+  'MACP_NO_CI_PIPELINE',
+  'MACP_NO_PROVIDER',
+  'MACP_AUTHORITY_REQUIRED',
+] as const;
+
+/** Raised when a required capability is missing and execution must fail closed. */
+export class MACPCapabilityError extends Error {
+  /** Typed error code from the closed MACP_ERROR_CODES set. */
+  readonly code: MacpErrorCode;
+  /** The missing capability, e.g. `ci-provider`, `task-persistence`, `command`. */
+  readonly capability: string;
+
+  constructor(code: MacpErrorCode, capability: string, message: string) {
+    super(message);
+    this.name = 'MACPCapabilityError';
+    this.code = code;
+    this.capability = capability;
+  }
+}

packages/macp/src/gate-runner.spec.ts

@@ -0,0 +1,429 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { countAIFindings, normalizeGate, runGate, runGates } from './gate-runner.js';
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'macp-gate-'));
+}
+
+describe('normalizeGate', () => {
+  it('normalizes a string to mechanical gate', () => {
+    expect(normalizeGate('echo test')).toEqual({
+      command: 'echo test',
+      type: 'mechanical',
+      fail_on: 'blocker',
+    });
+  });
+
+  it('normalizes an object gate with defaults', () => {
+    expect(normalizeGate({ command: 'lint' })).toEqual({
+      command: 'lint',
+      type: 'mechanical',
+      fail_on: 'blocker',
+    });
+  });
+
+  it('preserves explicit type and fail_on', () => {
+    expect(normalizeGate({ command: 'review', type: 'ai-review', fail_on: 'any' })).toEqual({
+      command: 'review',
+      type: 'ai-review',
+      fail_on: 'any',
+    });
+  });
+
+  it('handles non-string/non-object input', () => {
+    expect(normalizeGate(42)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
+    expect(normalizeGate(null)).toEqual({ command: '', type: 'mechanical', fail_on: 'blocker' });
+  });
+});
+
+describe('countAIFindings', () => {
+  it('returns zeros for non-object', () => {
+    expect(countAIFindings(null)).toEqual({ blockers: 0, total: 0 });
+    expect(countAIFindings('string')).toEqual({ blockers: 0, total: 0 });
+    expect(countAIFindings([])).toEqual({ blockers: 0, total: 0 });
+  });
+
+  it('counts from stats block', () => {
+    const output = { stats: { blockers: 2, should_fix: 3, suggestions: 1 } };
+    expect(countAIFindings(output)).toEqual({ blockers: 2, total: 6 });
+  });
+
+  it('counts from findings array when stats has no blockers', () => {
+    const output = {
+      stats: { blockers: 0 },
+      findings: [{ severity: 'blocker' }, { severity: 'warning' }, { severity: 'blocker' }],
+    };
+    expect(countAIFindings(output)).toEqual({ blockers: 2, total: 3 });
+  });
+
+  it('uses stats blockers over findings array when stats has blockers', () => {
+    const output = {
+      stats: { blockers: 5 },
+      findings: [{ severity: 'blocker' }, { severity: 'warning' }],
+    };
+    // stats.blockers = 5, total from stats = 5+0+0 = 5, findings not used for total since stats total is non-zero
+    expect(countAIFindings(output)).toEqual({ blockers: 5, total: 5 });
+  });
+
+  it('counts findings length as total when stats has zero total', () => {
+    const output = {
+      findings: [{ severity: 'warning' }, { severity: 'info' }],
+    };
+    expect(countAIFindings(output)).toEqual({ blockers: 0, total: 2 });
+  });
+});
+
+describe('runGate', () => {
+  let tmp: string;
+  let logPath: string;
+
+  beforeEach(() => {
+    tmp = makeTmpDir();
+    logPath = path.join(tmp, 'gate.log');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('passes mechanical gate on exit 0', () => {
+    const result = runGate('echo hello', tmp, logPath, 30);
+    expect(result.passed).toBe(true);
+    expect(result.exit_code).toBe(0);
+    expect(result.type).toBe('mechanical');
+    expect(result.output).toContain('hello');
+  });
+
+  it('fails mechanical gate on non-zero exit', () => {
+    const result = runGate('exit 1', tmp, logPath, 30);
+    expect(result.passed).toBe(false);
+    expect(result.exit_code).toBe(1);
+  });
+
+  it('ci-pipeline fails closed without a CI provider (no placeholder pass)', () => {
+    const result = runGate({ command: 'anything', type: 'ci-pipeline' }, tmp, logPath, 30);
+    expect(result.passed).toBe(false);
+    expect(result.status).toBe('capability_failure');
+    expect(result.capability_code).toBe('MACP_NO_CI_PIPELINE');
+    expect(result.type).toBe('ci-pipeline');
+    expect(result.output).not.toBe('CI pipeline gate placeholder');
+  });
+
+  it('empty command is a typed capability failure, never a pass', () => {
+    const result = runGate({ command: '' }, tmp, logPath, 30);
+    expect(result.passed).toBe(false);
+    expect(result.status).toBe('capability_failure');
+    expect(result.capability_code).toBe('MACP_NO_COMMAND');
+  });
+
+  it('ai-review gate parses JSON output', () => {
+    const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
+    const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
+    expect(result.passed).toBe(true);
+    expect(result.blockers).toBe(0);
+    expect(result.findings).toBe(1);
+  });
+
+  it('ai-review gate fails on blockers', () => {
+    const json = JSON.stringify({ stats: { blockers: 2 } });
+    const result = runGate({ command: `echo '${json}'`, type: 'ai-review' }, tmp, logPath, 30);
+    expect(result.passed).toBe(false);
+    expect(result.blockers).toBe(2);
+  });
+
+  it('ai-review gate with fail_on=any fails on any findings', () => {
+    const json = JSON.stringify({ stats: { blockers: 0, should_fix: 1 } });
+    const result = runGate(
+      { command: `echo '${json}'`, type: 'ai-review', fail_on: 'any' },
+      tmp,
+      logPath,
+      30,
+    );
+    expect(result.passed).toBe(false);
+    expect(result.fail_on).toBe('any');
+  });
+
+  it('ai-review gate fails on invalid JSON output', () => {
+    const result = runGate({ command: 'echo "not json"', type: 'ai-review' }, tmp, logPath, 30);
+    expect(result.passed).toBe(false);
+    expect(result.parse_error).toBeDefined();
+  });
+
+  it('writes to log file', () => {
+    runGate('echo logged', tmp, logPath, 30);
+    const log = fs.readFileSync(logPath, 'utf-8');
+    expect(log).toContain('COMMAND: echo logged');
+    expect(log).toContain('logged');
+    expect(log).toContain('EXIT:');
+  });
+});
+
+describe('runGates', () => {
+  let tmp: string;
+  let logPath: string;
+  let eventsPath: string;
+
+  beforeEach(() => {
+    tmp = makeTmpDir();
+    logPath = path.join(tmp, 'gates.log');
+    eventsPath = path.join(tmp, 'events.ndjson');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('runs multiple gates and returns results', () => {
+    const { allPassed, gateResults } = runGates(
+      ['echo one', 'echo two'],
+      tmp,
+      logPath,
+      30,
+      eventsPath,
+      'task-1',
+    );
+    expect(allPassed).toBe(true);
+    expect(gateResults).toHaveLength(2);
+  });
+
+  it('reports failure when any gate fails', () => {
+    const { allPassed, gateResults } = runGates(
+      ['echo ok', 'exit 1'],
+      tmp,
+      logPath,
+      30,
+      eventsPath,
+      'task-2',
+    );
+    expect(allPassed).toBe(false);
+    expect(gateResults[0]!.passed).toBe(true);
+    expect(gateResults[1]!.passed).toBe(false);
+  });
+
+  it('emits events for each gate', () => {
+    runGates(['echo test'], tmp, logPath, 30, eventsPath, 'task-3');
+    const events = fs
+      .readFileSync(eventsPath, 'utf-8')
+      .trim()
+      .split('\n')
+      .map((l) => JSON.parse(l));
+    expect(events).toHaveLength(2); // started + passed
+    expect(events[0].event_type).toBe('rail.check.started');
+    expect(events[1].event_type).toBe('rail.check.passed');
+  });
+
+  it('does not silently skip gates with empty command — they become capability failures', () => {
+    const { gateResults, allPassed, state } = runGates(
+      [{ command: '', type: 'mechanical' }, 'echo real'],
+      tmp,
+      logPath,
+      30,
+      eventsPath,
+      'task-4',
+    );
+    expect(gateResults).toHaveLength(2);
+    expect(gateResults[0]!.status).toBe('capability_failure');
+    expect(gateResults[1]!.status).toBe('passed');
+    expect(allPassed).toBe(false);
+    expect(state).toBe('capability_failure');
+  });
+
+  it('does not skip ci-pipeline even with empty command — typed capability failure', () => {
+    const { gateResults, allPassed, state } = runGates(
+      [{ command: '', type: 'ci-pipeline' }],
+      tmp,
+      logPath,
+      30,
+      eventsPath,
+      'task-5',
+    );
+    expect(gateResults).toHaveLength(1);
+    expect(gateResults[0]!.passed).toBe(false);
+    expect(gateResults[0]!.status).toBe('capability_failure');
+    expect(allPassed).toBe(false);
+    expect(state).toBe('capability_failure');
+  });
+
+  it('emits failed event with correct message', () => {
+    runGates(['exit 42'], tmp, logPath, 30, eventsPath, 'task-6');
+    const events = fs
+      .readFileSync(eventsPath, 'utf-8')
+      .trim()
+      .split('\n')
+      .map((l) => JSON.parse(l));
+    const failEvent = events.find(
+      (e: Record<string, unknown>) => e.event_type === 'rail.check.failed',
+    );
+    expect(failEvent).toBeDefined();
+    expect(failEvent.message).toContain('Gate failed (');
+  });
+});
+
+/**
+ * RI-N2 / SDLC-D-035 fail-closed controls for the MACP gate runner.
+ *
+ * Invariant under test: `passed: true` occurs ONLY when a gate really executed
+ * and really exited green (`status === 'passed'`). Absent capabilities,
+ * manual sign-offs, and simulated runs are typed distinctly and can never
+ * make the aggregate `passed`.
+ */
+describe('gate-runner fail-closed (RI-N2)', () => {
+  let tmpDir: string;
+  let logPath: string;
+  let eventsPath: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    logPath = path.join(tmpDir, 'gate.log');
+    eventsPath = path.join(tmpDir, 'events.ndjson');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function run(gates: unknown[], options?: { simulate?: boolean }) {
+    return runGates(gates, tmpDir, logPath, 10, eventsPath, 'spec-task', options);
+  }
+
+  // ─── positive controls ───────────────────────────────────────────────────
+
+  it('a really-executed green command gate still passes', () => {
+    const result = run([{ command: 'exit 0', type: 'mechanical' }]);
+    expect(result.gateResults[0]!.status).toBe('passed');
+    expect(result.gateResults[0]!.passed).toBe(true);
+    expect(result.allPassed).toBe(true);
+    expect(result.state).toBe('passed');
+  });
+
+  it('explicit simulate completes and types every result simulated', () => {
+    const result = run([{ command: 'exit 0', type: 'mechanical' }, 'echo hello'], {
+      simulate: true,
+    });
+    expect(result.gateResults).toHaveLength(2);
+    for (const gate of result.gateResults) {
+      expect(gate.status).toBe('simulated');
+      expect(gate.passed).toBe(false);
+    }
+    expect(result.state).toBe('simulated');
+  });
+
+  it('a really-executed red command gate fails with typed status failed', () => {
+    const result = run([{ command: 'exit 3', type: 'mechanical' }]);
+    expect(result.gateResults[0]!.status).toBe('failed');
+    expect(result.gateResults[0]!.passed).toBe(false);
+    expect(result.allPassed).toBe(false);
+    expect(result.state).toBe('failed');
+  });
+
+  // ─── negative controls — each asserts typed status AND aggregate not passed ──
+
+  it('an empty-command gate is a capability_failure, not skipped and not passed', () => {
+    const result = run([{ command: '', type: 'mechanical' }]);
+    // runGates must not silently skip it — it produces a typed result
+    expect(result.gateResults).toHaveLength(1);
+    const gate = result.gateResults[0]!;
+    expect(gate.status).toBe('capability_failure');
+    expect(gate.capability_code).toBe('MACP_NO_COMMAND');
+    expect(gate.passed).toBe(false);
+    // aggregate is not passed
+    expect(result.allPassed).toBe(false);
+    expect(result.state).toBe('capability_failure');
+    expect(result.state).not.toBe('passed');
+  });
+
+  it('a commandless ai-review gate is a typed MACP_NO_REVIEWER capability_failure', () => {
+    const result = run([{ command: '', type: 'ai-review' }]);
+    expect(result.gateResults[0]!.status).toBe('capability_failure');
+    expect(result.gateResults[0]!.capability_code).toBe('MACP_NO_REVIEWER');
+    expect(result.allPassed).toBe(false);
+    expect(result.state).not.toBe('passed');
+  });
+
+  it('a ci-pipeline gate without a provider implementation is a capability_failure, never a placeholder pass', () => {
+    const result = run([{ command: '', type: 'ci-pipeline' }]);
+    const gate = result.gateResults[0]!;
+    expect(gate.status).toBe('capability_failure');
+    expect(gate.capability_code).toBe('MACP_NO_CI_PIPELINE');
+    expect(gate.passed).toBe(false);
+    // the old false-success placeholder must be gone
+    expect(gate.output).not.toBe('CI pipeline gate placeholder');
+    expect(result.allPassed).toBe(false);
+    expect(result.state).not.toBe('passed');
+  });
+
+  it('a ci-pipeline gate fails closed even alongside an otherwise green run', () => {
+    const result = run(['exit 0', { type: 'ci-pipeline', command: 'fake-ci' }]);
+    expect(result.gateResults[1]!.status).toBe('capability_failure');
+    expect(result.gateResults[0]!.status).toBe('passed');
+    expect(result.allPassed).toBe(false);
+    expect(result.state).toBe('capability_failure');
+  });
+
+  it('a manual gate with no automation enters typed waiting — neither pass nor fail', () => {
+    const result = run([{ type: 'manual' }]);
+    const gate = result.gateResults[0]!;
+    expect(gate.status).toBe('waiting');
+    expect(gate.passed).toBe(false);
+    expect(gate.exit_code).toBe(0);
+    // aggregate is not passed while any gate is waiting
+    expect(result.allPassed).toBe(false);
+    expect(result.state).toBe('waiting');
+    expect(result.state).not.toBe('passed');
+  });
+
+  it('a simulated result can never make the aggregate passed', () => {
+    const result = run(['exit 0', 'exit 0'], { simulate: true });
+    expect(result.gateResults.every((g) => g.status === 'simulated')).toBe(true);
+    expect(result.allPassed).toBe(false);
+    expect(result.state).toBe('simulated');
+    expect(result.state).not.toBe('passed');
+  });
+
+  it('waiting dominates an otherwise green aggregate', () => {
+    const result = run(['exit 0', { type: 'manual' }]);
+    expect(result.allPassed).toBe(false);
+    expect(result.state).toBe('waiting');
+  });
+});
+
+describe('runGate fail-closed (RI-N2)', () => {
+  let tmpDir: string;
+  let logPath: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    logPath = path.join(tmpDir, 'gate.log');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('simulate: true returns a typed simulated result without executing', () => {
+    const result = runGate('this-command-does-not-exist-xyz', tmpDir, logPath, 10, {
+      simulate: true,
+    });
+    expect(result.status).toBe('simulated');
+    expect(result.passed).toBe(false);
+    expect(result.exit_code).toBe(0);
+  });
+
+  it('normal mode executes for real and types a green gate passed', () => {
+    const result = runGate('echo ok', tmpDir, logPath, 10);
+    expect(result.status).toBe('passed');
+    expect(result.passed).toBe(true);
+    expect(result.output).toContain('ok');
+  });
+
+  it('a bare string gate normalizes to mechanical and executes', () => {
+    const result = runGate('exit 7', tmpDir, logPath, 10);
+    expect(result.type).toBe('mechanical');
+    expect(result.status).toBe('failed');
+    expect(result.passed).toBe(false);
+  });
+});

packages/macp/src/gate-runner.ts

@@ -4,7 +4,20 @@ import { dirname } from 'node:path';
 
 import { emitEvent } from './event-emitter.js';
 import { nowISO } from './event-emitter.js';
-import type { GateResult } from './types.js';
+import type { GateResult, GateStatus, RunGatesResult } from './types.js';
+
+/** Typed reason stamped on every simulated gate result. */
+export const SIMULATED_GATE_REASON =
+  'simulated execution (explicit simulate opt-in): gate was not evaluated by a real implementation';
+
+/** Options for gate execution (RI-N2 fail-closed / explicit simulation). */
+export interface RunGateOptions {
+  /**
+   * Explicit caller opt-in to simulation. Simulated gates are NOT executed;
+   * every result is typed `simulated` and never satisfies anything.
+   */
+  simulate?: boolean;
+}
 
 export interface NormalizedGate {
   command: string;
@@ -103,36 +116,91 @@ export function countAIFindings(parsedOutput: unknown): { blockers: number; tota
   return { blockers, total };
 }
 
+function simulatedResult(gateEntry: NormalizedGate): GateResult {
+  return {
+    command: gateEntry.command,
+    exit_code: 0,
+    type: gateEntry.type,
+    output: SIMULATED_GATE_REASON,
+    timed_out: false,
+    passed: false,
+    status: 'simulated',
+    reason: SIMULATED_GATE_REASON,
+  };
+}
+
+function capabilityFailureResult(
+  gateEntry: NormalizedGate,
+  code: GateResult['capability_code'],
+  reason: string,
+): GateResult {
+  return {
+    command: gateEntry.command,
+    exit_code: 1,
+    type: gateEntry.type,
+    output: '',
+    timed_out: false,
+    passed: false,
+    status: 'capability_failure',
+    capability_code: code,
+    reason,
+  };
+}
+
+function waitingResult(gateEntry: NormalizedGate, reason: string): GateResult {
+  return {
+    command: gateEntry.command,
+    exit_code: 0,
+    type: gateEntry.type,
+    output: '',
+    timed_out: false,
+    passed: false,
+    status: 'waiting',
+    capability_code: 'MACP_AUTHORITY_REQUIRED',
+    reason,
+  };
+}
+
 export function runGate(
   gate: unknown,
   cwd: string,
   logPath: string,
   timeoutSec: number,
+  options: RunGateOptions = {},
 ): GateResult {
   const gateEntry = normalizeGate(gate);
   const gateType = gateEntry.type;
   const command = gateEntry.command;
 
+  // Explicit simulation only: never executes, typed simulated, never satisfying.
+  if (options.simulate) {
+    return simulatedResult(gateEntry);
+  }
+
+  // Fail closed: no CI provider implementation exists in @mosaicstack/macp,
+  // so a ci-pipeline gate is an absent capability — never a placeholder pass.
   if (gateType === 'ci-pipeline') {
-    return {
+    return capabilityFailureResult(
-      command,
+      gateEntry,
-      exit_code: 0,
+      'MACP_NO_CI_PIPELINE',
-      type: gateType,
+      `ci-pipeline gate '${gateEntry.command || gateType}' has no CI provider implementation wired — refusing placeholder pass`,
-      output: 'CI pipeline gate placeholder',
+    );
-      timed_out: false,
-      passed: true,
-    };
   }
 
   if (!command) {
-    return {
+    // A manual gate with no automation waits for human sign-off: not pass, not fail.
-      command: '',
+    if (gateType === 'manual') {
-      exit_code: 0,
+      return waitingResult(
-      type: gateType,
+        gateEntry,
-      output: '',
+        `manual gate has no automation — waiting for human sign-off (type: ${gateType})`,
-      timed_out: false,
+      );
-      passed: true,
+    }
-    };
+    // Any other commandless gate is an absent capability — never a vacuous pass.
+    return capabilityFailureResult(
+      gateEntry,
+      gateType === 'ai-review' ? 'MACP_NO_REVIEWER' : 'MACP_NO_COMMAND',
+      `gate of type '${gateType}' has no command to execute — refusing empty-command pass`,
+    );
   }
 
   const { exitCode, output, timedOut } = runShell(command, cwd, logPath, timeoutSec);
@@ -143,10 +211,12 @@ export function runGate(
     output,
     timed_out: timedOut,
     passed: false,
+    status: 'failed',
   };
 
   if (gateType !== 'ai-review') {
     result.passed = exitCode === 0;
+    result.status = result.passed ? 'passed' : 'failed';
     return result;
   }
 
@@ -170,6 +240,7 @@ export function runGate(
   } else {
     result.passed = exitCode === 0 && blockers === 0 && !timedOut && parseError === undefined;
   }
+  result.status = result.passed ? 'passed' : 'failed';
 
   result.fail_on = failOn;
   result.blockers = blockers;
@@ -191,16 +262,19 @@ export function runGates(
   timeoutSec: number,
   eventsPath: string,
   taskId: string,
-): { allPassed: boolean; gateResults: GateResult[] } {
+  options: RunGateOptions = {},
-  let allPassed = true;
+): RunGatesResult {
   const gateResults: GateResult[] = [];
+  let hasCapabilityFailure = false;
+  let hasSimulated = false;
+  let hasFailed = false;
+  let hasWaiting = false;
 
   for (const gate of gates) {
     const gateEntry = normalizeGate(gate);
     const gateCmd = gateEntry.command;
-    if (!gateCmd && gateEntry.type !== 'ci-pipeline') continue;
-
     const label = gateCmd || gateEntry.type;
+    // NOTE: no silent skip — every gate produces a typed result (RI-N2).
     emitEvent(
       eventsPath,
       'rail.check.started',
@@ -209,10 +283,10 @@ export function runGates(
       'quality-gate',
       `Running gate: ${label}`,
     );
-    const result = runGate(gate, cwd, logPath, timeoutSec);
+    const result = runGate(gate, cwd, logPath, timeoutSec, options);
     gateResults.push(result);
 
-    if (result.passed) {
+    if (result.status === 'passed') {
       emitEvent(
         eventsPath,
         'rail.check.passed',
@@ -224,7 +298,46 @@ export function runGates(
       continue;
     }
 
-    allPassed = false;
+    if (result.status === 'waiting') {
+      hasWaiting = true;
+      emitEvent(
+        eventsPath,
+        'rail.check.waiting',
+        taskId,
+        'gated',
+        'quality-gate',
+        `Gate waiting: ${label} — ${result.reason ?? 'manual gate awaits sign-off'}`,
+      );
+      continue;
+    }
+
+    if (result.status === 'simulated') {
+      hasSimulated = true;
+      emitEvent(
+        eventsPath,
+        'rail.check.simulated',
+        taskId,
+        'gated',
+        'quality-gate',
+        `Gate simulated (non-satisfying): ${label}`,
+      );
+      continue;
+    }
+
+    if (result.status === 'capability_failure') {
+      hasCapabilityFailure = true;
+      emitEvent(
+        eventsPath,
+        'rail.check.failed',
+        taskId,
+        'gated',
+        'quality-gate',
+        `Gate capability failure (${result.capability_code ?? 'MACP_NO_PROVIDER'}): ${label} — ${result.reason ?? 'required capability is absent'}`,
+      );
+      continue;
+    }
+
+    hasFailed = true;
     let message: string;
     if (result.timed_out) {
       message = `Gate timed out after ${timeoutSec}s: ${label}`;
@@ -236,5 +349,15 @@ export function runGates(
     emitEvent(eventsPath, 'rail.check.failed', taskId, 'gated', 'quality-gate', message);
   }
 
-  return { allPassed, gateResults };
+  const state: GateStatus = hasCapabilityFailure
+    ? 'capability_failure'
+    : hasSimulated
+      ? 'simulated'
+      : hasFailed
+        ? 'failed'
+        : hasWaiting
+          ? 'waiting'
+          : 'passed';
+
+  return { allPassed: state === 'passed', gateResults, state };
 }

packages/macp/src/index.ts

@@ -6,11 +6,13 @@ export type {
   DependsOnPolicy,
   GateType,
   GateFailOn,
+  GateStatus,
   GateEntry,
   Task,
   EventType,
   MACPEvent,
   GateResult,
+  RunGatesResult,
   TaskResult,
   ProviderMeta,
   ProviderRegistry,
@@ -18,6 +20,11 @@ export type {
 
 export { CredentialError } from './types.js';
 
+// Typed fail-closed capability errors (RI-N2, SDLC-D-035)
+export { MACP_ERROR_CODES, MACPCapabilityError } from './errors.js';
+
+export type { MacpErrorCode } from './errors.js';
+
 // Credential resolver
 export {
   DEFAULT_CREDENTIALS_DIR,
@@ -35,9 +42,16 @@ export {
 export type { ResolveCredentialsOptions } from './credential-resolver.js';
 
 // Gate runner
-export { normalizeGate, runShell, countAIFindings, runGate, runGates } from './gate-runner.js';
+export {
+  normalizeGate,
+  runShell,
+  countAIFindings,
+  runGate,
+  runGates,
+  SIMULATED_GATE_REASON,
+} from './gate-runner.js';
 
-export type { NormalizedGate } from './gate-runner.js';
+export type { NormalizedGate, RunGateOptions } from './gate-runner.js';
 
 // Risk-floor (agent reflection loop — diff review classifier)
 export { evaluateRiskFloor, DEFAULT_RISK_THRESHOLD } from './risk-floor.js';

packages/macp/src/types.ts

@@ -1,3 +1,5 @@
+import type { MacpErrorCode } from './errors.js';
+
 /** Task status values. */
 export type TaskStatus = 'pending' | 'running' | 'gated' | 'completed' | 'failed' | 'escalated';
 
@@ -17,7 +19,17 @@ export type DispatchMode = 'yolo' | 'acp' | 'exec';
 export type DependsOnPolicy = 'all' | 'any' | 'all_terminal';
 
 /** Quality gate type. */
-export type GateType = 'mechanical' | 'ai-review' | 'ci-pipeline';
+export type GateType = 'mechanical' | 'ai-review' | 'ci-pipeline' | 'manual';
+
+/**
+ * Typed execution state of a gate — closed set (RI-N2, SDLC-D-035).
+ *
+ * Only `passed` means "really executed and green". `simulated` is produced
+ * exclusively under an explicit simulate opt-in and never satisfies anything.
+ * `capability_failure` means a required executor/provider/command was absent.
+ * `waiting` means a manual gate awaits human sign-off (neither pass nor fail).
+ */
+export type GateStatus = 'passed' | 'failed' | 'simulated' | 'waiting' | 'capability_failure';
 
 /** Gate fail_on mode. */
 export type GateFailOn = 'blocker' | 'any';
@@ -67,7 +79,9 @@ export type EventType =
   | 'task.retry.scheduled'
   | 'rail.check.started'
   | 'rail.check.passed'
-  | 'rail.check.failed';
+  | 'rail.check.failed'
+  | 'rail.check.waiting'
+  | 'rail.check.simulated';
 
 /** Structured event record. */
 export interface MACPEvent {
@@ -88,7 +102,14 @@ export interface GateResult {
   type: string;
   output: string;
   timed_out: boolean;
+  /** Back-compat boolean view — true ONLY when `status === 'passed'`. */
   passed: boolean;
+  /** Typed discriminator — the authoritative gate outcome (RI-N2). */
+  status: GateStatus;
+  /** Typed capability error code, set when `status === 'capability_failure'`. */
+  capability_code?: MacpErrorCode;
+  /** Why a non-executed state (simulated/waiting/capability_failure) was reached. */
+  reason?: string;
   fail_on?: string;
   blockers?: number;
   findings?: number;
@@ -96,6 +117,22 @@ export interface GateResult {
   parse_error?: string;
 }
 
+/**
+ * Aggregate outcome of `runGates` (RI-N2).
+ *
+ * `state` is the typed aggregate: it is `passed` only when every gate really
+ * executed green. A `simulated` result makes the aggregate `simulated` (never
+ * `passed`); a `waiting` manual gate keeps the aggregate `waiting`; a missing
+ * capability makes it `capability_failure`. `allPassed` is exactly
+ * `state === 'passed'`, so a simulated or waiting result can never satisfy a
+ * dependency, acceptance criterion, gate, merge, or release check.
+ */
+export interface RunGatesResult {
+  allPassed: boolean;
+  gateResults: GateResult[];
+  state: GateStatus;
+}
+
 /** Result from a completed task. */
 export interface TaskResult {
   task_id: string;

packages/mosaic/framework/install.sh

@@ -35,6 +35,18 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 
+# Normalize the ambient umask so directory modes are a property of the installer
+# and not of whatever shell invoked it (#1236). Debian/Ubuntu ship umask 002, so
+# every `mkdir -p` below yielded 0775 — and the fleet env boundary rejects any
+# managed directory with `mode & 0o022`, which made `mosaic fleet init --write`
+# impossible on a stock install of those distros. Fedora/RHEL ship 022 and did
+# not trip it, so the product worked or did not depending on the operator's
+# login shell. 022 is what this script already assumes it produces: see the
+# umask note in make_durable_snapshot, which restores to the ambient value
+# precisely so "every later sync copy and new framework dir" gets 0644/0755.
+# Now that value is 022 rather than whatever was inherited.
+umask 022
+
 # Deliberately parsed from "$@" (a real, explicit, per-invocation argument) —
 # never an environment variable — so this opt-out can never sit silently
 # inherited in a shell profile. See #869 Point-1 C2.
@@ -696,6 +708,52 @@ sync_framework
 mkdir -p "$TARGET_DIR/memory"
 mkdir -p "$TARGET_DIR/credentials"
 
+# Three directories must be 0700, not merely not-group-writable (#1236).
+# The fleet code guards them with two different masks in two different
+# languages, and the strict one wins:
+#
+#   assertPrivateManagedDirectory (fleet-reconciler.js, `mode & 0o077`)
+#       -> MOSAIC_HOME and MOSAIC_HOME/fleet, checked before the roster lock is
+#          taken, so every mutating `mosaic fleet` command dies at 0755.
+#   assert_private_directory (tools/fleet/start-agent-session.sh, `mode & 077`)
+#       -> MOSAIC_HOME/fleet/agents, checked before a pane is ever spawned.
+#
+# Their laxer siblings (`mode & 0o022`) accept 0755, which is why normalizing
+# the umask above is necessary and not sufficient — a correct umask-022 install
+# still produces 0755 and still cannot run `mosaic fleet init --write`. Say the
+# strict modes outright rather than inferring them from a umask.
+#
+# Only these. The rest of the tree is content, stays 0755, and is only ever
+# reached by the 0o022 checks, which 0755 satisfies.
+chmod 700 "$TARGET_DIR" 2>/dev/null || \
+  warn "Could not set 0700 on $TARGET_DIR — 'mosaic fleet' mutations will fail as unsafe-permissions."
+if [[ -d "$TARGET_DIR/fleet" ]]; then
+  chmod 700 "$TARGET_DIR/fleet" 2>/dev/null || \
+    warn "Could not set 0700 on $TARGET_DIR/fleet — 'mosaic fleet' mutations will fail as unsafe-permissions."
+fi
+# fleet/agents does not exist on a first install — the CLI creates it 0700 on
+# demand. It is chmod'd here for the UPGRADE case: a tree built under umask 002
+# has it at 0775, and the repair sweep below cannot rescue it, because stripping
+# group/other write from 0755 leaves 0750 and `mode & 077` is still non-zero.
+if [[ -d "$TARGET_DIR/fleet/agents" ]]; then
+  chmod 700 "$TARGET_DIR/fleet/agents" 2>/dev/null || \
+    warn "Could not set 0700 on $TARGET_DIR/fleet/agents — agent sessions will fail to start as unsafe-permissions."
+fi
+# credentials/ holds secrets and was never meant to be group-readable either.
+# It is not on the fleet boundary, so a failure here breaks nothing — but it is
+# the one directory where a silently-failed chmod leaves secrets group-readable,
+# which is precisely the failure worth a line in the output.
+chmod 700 "$TARGET_DIR/credentials" 2>/dev/null || \
+  warn "Could not set 0700 on $TARGET_DIR/credentials — stored secrets may be readable by other users on this host."
+
+# Repair an existing tree. The umask above only governs directories this run
+# creates, so a host installed under umask 002 before this fix keeps its 0775
+# dirs through every upgrade and stays broken. Strips group/other WRITE only —
+# never read or execute — so it can repair the boundary violation without
+# changing who can traverse or read anything. Scoped to directories: file modes
+# are the manifest's business, not this fix's.
+find "$TARGET_DIR" -type d -perm /022 -exec chmod go-w {} + 2>/dev/null || true
+
 # Reconcile contract files from defaults/ into the framework root: framework-owned
 # files (CONSTITUTION/AGENTS/STANDARDS) are overwritten every upgrade (a divergent
 # copy is backed up once); user-seeded files (TOOLS) are written on first install only.

packages/mosaic/framework/systemd/user/mosaic-agent@.service

@@ -4,6 +4,14 @@ Documentation=https://git.mosaicstack.dev/mosaicstack/stack
 Requires=mosaic-tmux-holder.service
 After=mosaic-tmux-holder.service
 PartOf=mosaic-tmux-holder.service
+# Do not attempt a seat before its generated env exists. `install` enables this
+# unit (WantedBy=default.target) but on a roster-v2 fleet the reconciler owns the
+# generated env, so between `install` and the first `apply`/`regen --write` there
+# is a boot window where ExecStart would run against an absent env file and the
+# launcher would fail the unit. A skipped unit is the honest state for "enabled
+# but not yet configured"; systemd re-evaluates the condition on every start, so
+# the seat comes up on the next start once the reconciler has written env.
+ConditionPathExists=%h/.config/mosaic/fleet/agents/%i.env.generated
 
 [Service]
 Type=oneshot

packages/mosaic/framework/systemd/user/test-fleet-units.sh

@@ -128,6 +128,14 @@ EOF
 sleep 30
 EOF
   chmod 700 "$AGENT_BIN/mosaic"
+  # The launcher resolves the roster's runtime against PANE_PATH before it
+  # spawns anything (#1241), so the runtime this projection names has to be
+  # present here even though the fake `mosaic` above never execs it.
+  cat > "$AGENT_BIN/pi" <<'EOF'
+#!/bin/sh
+sleep 30
+EOF
+  chmod 700 "$AGENT_BIN/pi"
   server_environment_before=$(tmux -L "$TEST_SOCKET" show-environment -g | sort)
   server_sessions_before=$(tmux -L "$TEST_SOCKET" list-sessions | sort)
   if /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin MOSAIC_HOME="$AGENT_HOME" \

packages/mosaic/framework/tools/_scripts/mosaic-doctor

@@ -225,6 +225,54 @@ else
   warn "mosaic-ensure-sequential-thinking helper missing"
 fi
 
+# Fleet transport binary (#1240).
+#
+# `mosaic fleet --help` reads "Manage the local Mosaic tmux fleet" and every
+# roster the CLI scaffolds sets `transport: tmux`, but nothing in the install
+# path provides tmux and, until now, nothing here noticed it was absent. On a
+# greenfield host that produced a fleet which installed clean, started clean,
+# and had no live seat; `mosaic fleet ps` was the operator's first and only
+# signal that anything was wrong.
+#
+# The roster's own `transport:` is read rather than assumed, so a host that
+# declares something other than tmux is told about the binary it actually
+# needs. Absent a roster the check still runs — `mosaic fleet init` will
+# scaffold a tmux fleet on this host, and finding out beforehand is the point.
+#
+# `tools/install.sh` carries a deliberately parallel check at the end of its
+# summary. The two are separate because the installer must be able to say this
+# before the framework's own scripts are guaranteed to be on disk; keep their
+# wording in step.
+fleet_declared_transport() {
+  local roster="$MOSAIC_HOME/fleet/roster.yaml"
+  local declared=""
+
+  if [[ -f "$roster" ]]; then
+    declared="$(sed -n 's/^[[:space:]]*transport:[[:space:]]*//p' "$roster" | head -1 |
+      tr -d '"'\''' | tr -d '\r' | awk '{print $1}')"
+  fi
+
+  printf '%s\n' "${declared:-tmux}"
+}
+
+check_fleet_transport() {
+  local transport
+  transport="$(fleet_declared_transport)"
+
+  if command -v "$transport" >/dev/null 2>&1; then
+    pass "Fleet transport available: $transport"
+    return
+  fi
+
+  if [[ -f "$MOSAIC_HOME/fleet/roster.yaml" ]]; then
+    warn "Fleet transport '$transport' is not installed — this host has a roster and no seat can launch. Install it (e.g. sudo apt-get install -y $transport), then 'mosaic fleet start'."
+  else
+    warn "Fleet transport '$transport' is not installed — 'mosaic fleet' cannot run seats here. Install it (e.g. sudo apt-get install -y $transport) before 'mosaic fleet init'."
+  fi
+}
+
+check_fleet_transport
+
 # Legacy migration surfaces should no longer contain symlink trees.
 legacy_paths=(
   "$HOME/.claude/agent-guides"

packages/mosaic/framework/tools/_scripts/test-fleet-transport-check.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Covers the #1240 fleet-transport checks in `mosaic-doctor` and in
+# `tools/install.sh`.
+#
+# Both checks answer the same question — "can a seat actually launch on this
+# host?" — from two different places, because the installer has to be able to
+# answer it before the framework's own scripts are guaranteed to be on disk.
+# Two implementations of one rule is exactly the shape that drifts, so this
+# harness drives BOTH, in one file, from the same table of cases.
+#
+# The functions are extracted from the shipped scripts rather than copied here.
+# A test that carries its own copy of the logic is a test that keeps passing
+# after the shipped copy changes — the failure mode this whole change is about.
+# Extraction is by exact function header and a closing brace in column one; if
+# either script is reshaped so that stops matching, the extraction yields
+# nothing and this fails loudly instead of silently measuring an empty string.
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+DOCTOR="$SCRIPT_DIR/mosaic-doctor"
+# framework/tools/_scripts -> framework/tools -> framework -> mosaic -> packages -> repo
+INSTALLER=$(cd -- "$SCRIPT_DIR/../../../../.." && pwd)/tools/install.sh
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+[ -f "$DOCTOR" ] || fail "missing mosaic-doctor at $DOCTOR"
+[ -f "$INSTALLER" ] || fail "missing install.sh at $INSTALLER"
+
+ROOT=$(mktemp -d)
+trap 'rm -rf "$ROOT"' EXIT
+
+# The cases below run with PATH set to a directory that deliberately does not
+# contain a shell, and a PATH assignment on a command also governs how that
+# command is looked up — so bash has to be named absolutely or it becomes the
+# thing that is missing.
+BASH_BIN=$(command -v bash) || fail "host is missing 'bash'"
+
+# A PATH containing exactly the utilities these functions use and nothing else.
+# The absent-transport cases are only meaningful on a PATH where the transport
+# is genuinely unresolvable, and this host (like most) has tmux in /usr/bin —
+# so the system path cannot be part of the path under test.
+FAKE_BIN="$ROOT/bin"
+mkdir -p "$FAKE_BIN"
+for utility in sed head tr awk; do
+  utility_path=$(command -v "$utility") || fail "host is missing '$utility'"
+  ln -s "$utility_path" "$FAKE_BIN/$utility"
+done
+
+if PATH="$FAKE_BIN" command -v tmux >/dev/null 2>&1; then
+  fail "'tmux' is resolvable on the minimal test path; absent-transport cases are not measurable"
+fi
+
+# Extract a function by its exact header, up to a closing brace in column one.
+extract_function() {
+  local source_file="$1"
+  local function_name="$2"
+  local destination="$3"
+
+  awk -v name="$function_name" '
+    $0 == name "() {" { collecting = 1 }
+    collecting { print }
+    collecting && $0 == "}" { exit }
+  ' "$source_file" > "$destination"
+
+  grep -qF "$function_name() {" "$destination" ||
+    fail "could not extract '$function_name' from $source_file — has it been renamed or reshaped?"
+  # An unterminated extraction would be a syntax error the moment it is sourced,
+  # but saying so here names the cause instead of leaving a bash parse error.
+  bash -n "$destination" ||
+    fail "extracted '$function_name' does not parse; the closing brace was probably not found"
+}
+
+extract_function "$DOCTOR" fleet_declared_transport "$ROOT/doctor-declared.sh"
+extract_function "$DOCTOR" check_fleet_transport "$ROOT/doctor-check.sh"
+extract_function "$INSTALLER" check_fleet_transport "$ROOT/installer-check.sh"
+
+# Build a MOSAIC_HOME, optionally with a roster declaring a transport.
+make_home() {
+  local home="$ROOT/$1"
+  local declared="${2-}"
+
+  rm -rf "$home"
+  mkdir -p "$home"
+  if [ -n "$declared" ]; then
+    mkdir -p "$home/fleet"
+    cat > "$home/fleet/roster.yaml" <<EOF
+version: 2
+generation: 1
+transport: $declared
+agents: []
+EOF
+  fi
+  printf '%s\n' "$home"
+}
+
+# Run the doctor's check against a given home and path, capturing which
+# reporter the check chose. The real `pass` prints only under `--verbose` and
+# the real `warn` always prints; these stubs make both unconditional on
+# purpose, because what is under test is the severity the check selects, not
+# whether the default verbosity happens to show it. A check that warned where
+# it should pass would otherwise be invisible here.
+run_doctor_check() {
+  local home="$1"
+  local path="$2"
+
+  MOSAIC_HOME="$home" PATH="$path" "$BASH_BIN" --noprofile --norc -c '
+    set -euo pipefail
+    warn() { echo "[WARN] $*"; }
+    pass() { echo "[OK] $*"; }
+    MOSAIC_HOME="$1"
+    source "$2"
+    source "$3"
+    check_fleet_transport
+  ' _ "$home" "$ROOT/doctor-declared.sh" "$ROOT/doctor-check.sh" 2>&1
+}
+
+run_installer_check() {
+  local home="$1"
+  local path="$2"
+
+  MOSAIC_HOME="$home" PATH="$path" "$BASH_BIN" --noprofile --norc -c '
+    set -euo pipefail
+    warn() { echo "[WARN] $*"; }
+    C="" RESET=""
+    MOSAIC_HOME="$1"
+    source "$2"
+    check_fleet_transport
+  ' _ "$home" "$ROOT/installer-check.sh" 2>&1
+}
+
+# A transport that exists. Named tmux because that is what the default roster
+# declares; the binary never runs, it only has to resolve.
+PRESENT_BIN="$ROOT/present-bin"
+mkdir -p "$PRESENT_BIN"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$PRESENT_BIN/tmux"
+chmod +x "$PRESENT_BIN/tmux"
+PATH_WITH_TMUX="$PRESENT_BIN:$FAKE_BIN"
+
+# ── absent, no roster ────────────────────────────────────────────────────────
+# Nothing has been configured yet, so the honest thing to point at is `init`.
+home=$(make_home no-roster)
+
+output=$(run_doctor_check "$home" "$FAKE_BIN")
+echo "$output" | grep -qF '[WARN]' || fail "doctor did not warn when tmux was absent"
+echo "$output" | grep -qF 'tmux' || fail "doctor warning did not name the transport"
+echo "$output" | grep -qF 'mosaic fleet init' || fail "doctor did not point a rosterless host at init"
+
+output=$(run_installer_check "$home" "$FAKE_BIN")
+echo "$output" | grep -qF '[WARN]' || fail "installer did not warn when tmux was absent"
+echo "$output" | grep -qF 'reports success and no seat comes up' ||
+  fail "installer warning did not say what the missing transport actually breaks"
+
+# ── absent, roster present ───────────────────────────────────────────────────
+# A configured fleet that cannot launch is a stronger statement than a
+# hypothetical one, and the message says so.
+home=$(make_home with-roster tmux)
+
+output=$(run_doctor_check "$home" "$FAKE_BIN")
+echo "$output" | grep -qF '[WARN]' || fail "doctor did not warn with a roster present and tmux absent"
+echo "$output" | grep -qF 'roster' || fail "doctor did not mention the roster it found"
+echo "$output" | grep -qF 'mosaic fleet start' || fail "doctor did not point a configured host at start"
+
+# ── present ──────────────────────────────────────────────────────────────────
+# Silence from the installer, and a pass (not a warning) from the audit.
+for home_name in no-roster with-roster; do
+  home="$ROOT/$home_name"
+
+  output=$(run_doctor_check "$home" "$PATH_WITH_TMUX")
+  if echo "$output" | grep -qF '[WARN]'; then
+    fail "doctor warned about the transport while tmux was present ($home_name)"
+  fi
+  echo "$output" | grep -qF '[OK]' || fail "doctor did not record a pass with tmux present ($home_name)"
+
+  output=$(run_installer_check "$home" "$PATH_WITH_TMUX")
+  if [ -n "$output" ]; then
+    fail "installer was not silent with tmux present ($home_name): $output"
+  fi
+done
+
+# ── the roster declares something other than tmux ────────────────────────────
+# The roster is read, not assumed. A host that declares a different transport
+# is told about the binary it actually needs, and never about tmux — being sent
+# to install the wrong package is worse than no advice at all.
+home=$(make_home other-transport zellij)
+
+output=$(run_doctor_check "$home" "$PATH_WITH_TMUX")
+echo "$output" | grep -qF 'zellij' || fail "doctor ignored the roster's declared transport"
+if echo "$output" | grep -qF 'tmux'; then
+  fail "doctor named tmux for a host whose roster declares zellij"
+fi
+
+output=$(run_installer_check "$home" "$PATH_WITH_TMUX")
+echo "$output" | grep -qF 'zellij' || fail "installer ignored the roster's declared transport"
+if echo "$output" | grep -qF 'tmux'; then
+  fail "installer named tmux for a host whose roster declares zellij"
+fi
+
+# ── a quoted or trailing-comment transport value ─────────────────────────────
+# YAML permits both and neither is exotic; a check that installs `tmux"` or
+# reads `tmux # default` as a binary name would send the operator nowhere.
+home=$(make_home quoted-transport '"tmux"   # the only transport today')
+
+output=$(run_doctor_check "$home" "$PATH_WITH_TMUX")
+echo "$output" | grep -qF '[OK] Fleet transport available: tmux' ||
+  fail "doctor did not parse a quoted/commented transport value: $output"
+
+output=$(run_installer_check "$home" "$PATH_WITH_TMUX")
+if [ -n "$output" ]; then
+  fail "installer did not parse a quoted/commented transport value: $output"
+fi
+
+echo "ok - fleet transport checks (mosaic-doctor + install.sh)"

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

@@ -286,6 +286,36 @@ _build_runtime_bin_prefix() {
 MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
 PANE_PATH=${MOSAIC_RUNTIME_BIN_PREFIX:+${MOSAIC_RUNTIME_BIN_PREFIX}:}/usr/local/bin:/usr/bin:/bin
 
+# #1241. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a cleared
+# environment. A binary missing from *that* path is a pane that dies in under a
+# second, inside a session nobody is attached to, with its diagnostic scrolled
+# into a pane tmux then destroys. Resolve both here, before any effect, where
+# the failure is still attributable to the thing that caused it.
+#
+# `mosaic yolo <runtime>` runs checkRuntime(runtime) and the binary it looks for
+# is named exactly like the runtime, so resolving the runtime name is the same
+# question the pane will ask a moment later — asked while an operator can still
+# see the answer.
+_resolve_in_pane_path() {
+  PATH="$PANE_PATH" command -v -- "$1" 2>/dev/null
+}
+
+# Exit 69 (EX_UNAVAILABLE): the seat cannot be provided. Distinguished from the
+# 64 (EX_USAGE) rejections above, which mean the projection itself was bad —
+# here the data is fine and the host is not ready. Callers tell the individual
+# cases apart by `code=`, the same way fail_env's many codes share exit 64.
+fail_launch() {
+  local code="$1"
+  shift
+  echo "ERROR: agent launch aborted: code=${code} agent=${AGENT_NAME} $*" >&2
+  exit 69
+}
+
+for required_binary in mosaic "$MOSAIC_AGENT_RUNTIME"; do
+  _resolve_in_pane_path "$required_binary" >/dev/null ||
+    fail_launch missing-binary "'${required_binary}' is not on the pane PATH (${PANE_PATH})"
+done
+
 _ensure_claude_workdir_trusted() {
   local workdir="$1"
   local resolved
@@ -384,6 +414,19 @@ if [ -n "$PANE_PID" ]; then
   _start_heartbeat_sidecar "$AGENT_NAME" "$PANE_PID" \
     "$MOSAIC_HEARTBEAT_RUN_DIR" "$MOSAIC_HEARTBEAT_INTERVAL" || \
     echo "WARNING: heartbeat sidecar could not be started for $AGENT_NAME" >&2
+elif _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
+  # #1241. Session present, no pane PID after a second of retries. Whatever this
+  # is, it is not a seat an operator can use, so it is not a success either.
+  fail_launch pane-pid-unresolved \
+    "tmux reports the session but no pane PID after 5 attempts"
 else
-  echo "WARNING: could not resolve pane PID for $AGENT_NAME — heartbeat sidecar not started" >&2
+  # #1241. This branch used to print a WARNING about the heartbeat sidecar and
+  # exit 0. It is not a heartbeat problem: tmux destroys a session when its pane
+  # command exits, so an absent session one second after new-session means the
+  # runtime died on startup. Reporting it as success is what let `fleet start`
+  # return 0 over three dead panes — the launcher knew, and said the wrong thing
+  # at the wrong severity to the wrong layer.
+  fail_launch pane-did-not-survive \
+    "the pane exited immediately and tmux destroyed the session;" \
+    "run 'mosaic yolo ${MOSAIC_AGENT_RUNTIME}' in ${MOSAIC_AGENT_WORKDIR} to see why"
 fi

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

@@ -23,8 +23,26 @@ index=0
 if [ "${args[0]:-}" = -L ]; then index=2; fi
 case "${args[$index]:-}" in
   has-session)
+    # The holder always answers. MOSAIC_TEST_HELD_SESSIONS lets a case add
+    # other targets that should answer too — without it there is no way to
+    # model "tmux still reports the session" for a non-holder agent, and the
+    # launcher's pane-pid-unresolved branch is unreachable from this harness.
+    #
+    # A listed target answers only AFTER new-session, because the launcher asks
+    # this question twice about the same name: once before launching, where a
+    # yes means "already running, nothing to do, exit 0", and once after, where
+    # a yes means "the session survived". A shim that answered yes to both
+    # would short-circuit at the first and never reach the branch under test —
+    # it would look like coverage and measure the idempotency path instead.
     for argument in "${args[@]}"; do
       [ "$argument" = '=_holder:0.0' ] && exit 0
+      case " ${MOSAIC_TEST_HELD_SESSIONS:-} " in
+        *" $argument "*)
+          if tr '\0' '\n' < "${MOSAIC_TEST_TMUX_CALLS:?}" | grep -qxF new-session; then
+            exit 0
+          fi
+          ;;
+      esac
     done
     exit 1
     ;;
@@ -62,6 +80,30 @@ env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
 SHIM
 chmod +x "$FAKE_BIN/mosaic"
 
+# The runtime the rosters below name. The launcher resolves it against PANE_PATH
+# before spawning (#1241), so it has to exist somewhere the pane would find it —
+# not merely on the launcher's own PATH.
+printf '#!/usr/bin/env bash\nexit 0\n' > "$FAKE_BIN/pi"
+chmod +x "$FAKE_BIN/pi"
+
+# PANE_PATH is derived partly from `npm config get prefix`. Left to the real npm
+# it would splice whatever the host has installed into the path under test, and
+# the missing-binary cases below would pass or fail by accident of the machine.
+cat > "$FAKE_BIN/npm" <<'SHIM'
+#!/usr/bin/env bash
+printf '%s\n' "${MOSAIC_TEST_NPM_PREFIX:-/nonexistent}"
+SHIM
+chmod +x "$FAKE_BIN/npm"
+
+# PANE_PATH always ends in the system path. A host that installs these there can
+# not measure the missing-binary cases at all, and a green run would mean
+# nothing — so say so instead of passing.
+for host_binary in mosaic pi; do
+  if PATH=/usr/local/bin:/usr/bin:/bin command -v "$host_binary" >/dev/null 2>&1; then
+    fail "host provides '$host_binary' in the system path; missing-binary cases are not measurable here"
+  fi
+done
+
 write_generated() {
   local home="$1"
   local agent="$2"
@@ -81,6 +123,19 @@ MOSAIC_TMUX_SOCKET=mosaic-test
 EOF
   chmod 600 "$home/fleet/agents/$agent.env.generated"
   mkdir -p "$home/work"
+  install_pane_binaries "$home"
+}
+
+# `$PANE_HOME/.npm-global/bin` is one of the prefixes the launcher folds into
+# PANE_PATH, so this is the pane's own view of "installed", distinct from the
+# launcher's PATH. Tests that need a binary *absent* remove it from here.
+install_pane_binaries() {
+  local pane_home="$1"
+  mkdir -p "$pane_home/.npm-global/bin"
+  local binary
+  for binary in mosaic pi; do
+    ln -sf "$FAKE_BIN/$binary" "$pane_home/.npm-global/bin/$binary"
+  done
 }
 
 run_start() {
@@ -88,6 +143,7 @@ run_start() {
   local agent="$2"
   HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
     MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
+    MOSAIC_TEST_HELD_SESSIONS="${MOSAIC_TEST_HELD_SESSIONS:-}" \
     MOSAIC_TEST_HOME="$home" \
     MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
     MOSAIC_HOME="$home" "$START" "$agent"
@@ -98,7 +154,10 @@ run_start() {
 HOME_VALID="$ROOT/valid"
 AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
-run_start "$HOME_VALID" "$AGENT_VALID"
+# A live pane PID is part of what "valid launch" means. Until #1241 this case
+# ran with none, so the suite's one success path was itself a dead pane the
+# launcher reported as fine.
+MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_VALID" "$AGENT_VALID"
 valid_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$valid_args" | grep -qF new-session || fail "valid generated projection did not reach tmux"
 echo "$valid_args" | grep -qF 'mosaic' || fail "fixed mosaic launcher command missing"
@@ -245,6 +304,13 @@ PANE_BASH_ENV="$ROOT/pane-boundary.bash-env"
 printf 'MOSAIC_RUNTIME_BIN=%s\n' "$FAKE_BIN" > \
   "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
 chmod 600 "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.local"
+# This case does not go through run_start, so its pane binaries come from
+# MOSAIC_RUNTIME_BIN=$FAKE_BIN in the env.local written above — not from the
+# symlinks install_pane_binaries planted under the generated home, which this
+# launcher never consults because HOME here is the trusted parent. That is a
+# legitimate resolution path, but it means dropping MOSAIC_RUNTIME_BIN from
+# this case on the belief that the symlinks cover it would break the #1241
+# binary check rather than exercise it.
 LD_PRELOAD='/not/loaded/by-clean-bootstrap.so' \
 BASH_ENV="$PANE_BASH_ENV" \
 MOSAIC_UNTRUSTED_SENTINEL='must-not-reach-pane' \
@@ -258,6 +324,7 @@ PATH="$PANE_STALE_PATH" \
     "MOSAIC_TEST_HOME=$PANE_TRUSTED_HOME" \
     MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
     MOSAIC_TEST_EXECUTE_PANE=1 \
+    "MOSAIC_TEST_PANE_PID=$$" \
     "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
 echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
@@ -392,6 +459,75 @@ echo "$interaction_policy_args" | grep -qF 'new-session' && \
 echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
   fail "interaction pinned-policy check did not follow strict parsing"
 
+# #1241. The pane runs `mosaic yolo <runtime>` against PANE_PATH. A binary
+# missing from that path is a launch failure, and it has to be named before the
+# session is created — after it, the diagnostic dies with the pane.
+assert_missing_pane_binary_rejected() {
+  local binary="$1"
+  local home="$ROOT/missing-$binary"
+  local agent="coder-missing-$binary"
+  write_generated "$home" "$agent"
+  rm -f "$home/.npm-global/bin/$binary"
+
+  : > "$TMUX_CALLS"
+  local output
+  if output=$(MOSAIC_TEST_PANE_PID=$$ run_start "$home" "$agent" 2>&1); then
+    fail "launch succeeded with '$binary' absent from the pane PATH"
+  fi
+  echo "$output" | grep -qF 'code=missing-binary' || fail "missing '$binary' diagnostic missing"
+  echo "$output" | grep -qF "'$binary'" || fail "missing-binary diagnostic did not name $binary"
+  if tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session; then
+    fail "launcher created a session it knew would die ($binary absent)"
+  fi
+}
+
+assert_missing_pane_binary_rejected mosaic
+assert_missing_pane_binary_rejected pi
+
+# #1241. tmux destroys a session when its pane command exits, so no pane PID a
+# second after new-session means the runtime died on startup. This used to be a
+# WARNING about the heartbeat sidecar followed by exit 0 — three layers above it
+# then reported a fleet that was not running.
+: > "$TMUX_CALLS"
+HOME_DEAD_PANE="$ROOT/dead-pane"
+write_generated "$HOME_DEAD_PANE" "coder-dead-pane"
+if output=$(MOSAIC_TEST_PANE_PID='' run_start "$HOME_DEAD_PANE" coder-dead-pane 2>&1); then
+  fail "launcher reported success over a pane that did not survive"
+fi
+echo "$output" | grep -qF 'code=pane-did-not-survive' || fail "dead-pane diagnostic missing"
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "dead pane is still being reported as a heartbeat-sidecar problem"
+fi
+tr '\0' '\n' < "$TMUX_CALLS" | grep -qF new-session || \
+  fail "dead-pane case did not reach the launch it is measuring"
+
+# #1241, the other way a pane fails. Above, tmux destroyed the session and
+# has-session said so. Here the session is still there and no PID comes back
+# after the retries — a different fault (the pane is alive but unusable, or
+# tmux is answering inconsistently) that an operator has to be told apart from
+# a runtime that died on startup.
+#
+# This case exists because the branch that handles it shipped with nothing able
+# to reach it: the shim answered has-session only for the holder, so every
+# non-holder agent landed in the session-is-gone branch no matter what. A
+# defensive branch nothing exercises is the same shape as the bug this whole
+# change is about, one layer down.
+: > "$TMUX_CALLS"
+HOME_NO_PID="$ROOT/pane-no-pid"
+write_generated "$HOME_NO_PID" "coder-no-pid"
+if output=$(MOSAIC_TEST_PANE_PID='' MOSAIC_TEST_HELD_SESSIONS='=coder-no-pid:0.0' \
+  run_start "$HOME_NO_PID" coder-no-pid 2>&1); then
+  fail "launcher reported success over a session with no resolvable pane PID"
+fi
+echo "$output" | grep -qF 'code=pane-pid-unresolved' || \
+  fail "session-present/no-PID was not reported as pane-pid-unresolved: $output"
+if echo "$output" | grep -qF 'code=pane-did-not-survive'; then
+  fail "a session tmux still reports was diagnosed as a destroyed session"
+fi
+if echo "$output" | grep -qiF 'heartbeat'; then
+  fail "an unresolvable pane PID is still being reported as a heartbeat-sidecar problem"
+fi
+
 # Exact stop derives the socket exclusively from the validated generated
 # projection and ignores an ambient socket supplied by the caller.
 : > "$TMUX_CALLS"

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -32,10 +32,6 @@ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a re
 packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)
 
 # --- single-suite directories: unmeasured in CI ---
-packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | unmeasured in CI image; stubs tmux via a fake bin dir, likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/glpi/test-list-http-status.sh | unmeasured in CI image; stub-based (#807 regression harness), likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/orchestrator/test-board-roll.sh | unmeasured in CI image; file-fixture based, likely CI-fit; #1017 burndown
-packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasured in CI image; drives ci-wait.sh against a stub pipeline-status.sh, likely CI-fit; #1017 burndown
 
 # --- naming-boundary files the strict test-*.sh prefix cannot even name ---
 # (#1017: three independent censuses handled the microtest file three different
@@ -43,3 +39,20 @@ packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasu
 # recorded judgement. These lines ARE that judgement, signed.)
 packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
 packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate
+
+# --- tools/fleet: precondition is unsatisfiable in the CI image (#1271) ---
+# Signed by fred (sb-it-1-dt, 2026-08-16) at origin/next 476db12.
+# This suite asserts the launcher's behaviour when `mosaic` and `pi` are MISSING.
+# It shims fakes into $FAKE_BIN, but the constructed PANE_PATH always ends in the
+# real system path, so on a host that installs those binaries the missing-binary
+# cases cannot be measured at all. The suite's own guard (line 103) says so and
+# fails rather than reporting a pass it cannot back. That guard is correct.
+# The error was wiring the suite into CI: #1017 (c56483eb) enumerated it and
+# dropped this exclusion, and the CI image provides `pi` in the system path, so
+# it has failed on every pipeline since. Measured 2026-08-16 across pipelines
+# 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in
+# each full log, identical, this assertion; control `zzz-not-present-zzz` -> 0.
+# Burn-down and the full measurement are tracked in #1271; unwired by PR #1270.
+# Because test:framework-shell is one && chain and this sat at position 44 of 48,
+# the four suites after it had not run at all since the merge.
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | precondition unsatisfiable in the CI image: asserts missing-binary behaviour, but PANE_PATH always ends in the system path and the image provides `pi` there; guard at line 103 fails by design rather than passing unmeasured. Burn down by controlling the tail of PANE_PATH inside the test. NOT by removing `pi` from the image: the CI image installs @earendil-works/[email protected] deliberately (measured in pipeline 2444's test-step log), and other suites depend on that pin. Burn-down tracked in #1271

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/commands/fleet-roster-v2-dispatch.spec.ts

@@ -0,0 +1,323 @@
+import { execFile } from 'node:child_process';
+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 => {
+  const unitPath = resolve(process.cwd(), 'framework', 'systemd', 'user', '[email protected]');
+
+  /** The single `ConditionPathExists=` value declared by the unit template. */
+  async function conditionPath(): Promise<string> {
+    const unit = await readFile(unitPath, 'utf8');
+    const matches = unit.match(/^ConditionPathExists=(.+)$/gm) ?? [];
+    expect(matches).toHaveLength(1);
+    return matches[0]!.slice('ConditionPathExists='.length).trim();
+  }
+
+  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.
+    expect(await conditionPath()).toBe('%h/.config/mosaic/fleet/agents/%i.env.generated');
+  });
+
+  /**
+   * The two halves of the guard's *effect*, which no assertion on the literal
+   * string can cover on its own.
+   *
+   * Measured end to end on a real box (canary, 2026-08-16) rather than inferred:
+   * with the condition, `systemctl --user start mosaic-agent@<name>` on an agent
+   * with no generated env returns rc=0, `Result=success`, `ConditionResult=no`,
+   * and journals "skipped, unmet condition check". With the condition removed by
+   * drop-in and nothing else changed, the same start returns rc=1,
+   * `Result=exit-code`, `ExecMainStatus=64`, and the unit enters `failed`.
+   *
+   * systemd is not available in this suite, so these two tests pin the parts
+   * that can drift in code: the condition naming a *different* file than the one
+   * the fleet actually writes, and the launcher quietly becoming tolerant of an
+   * absent env — either of which turns the condition into decoration while the
+   * literal-string assertion above still passes.
+   */
+  it('guards exactly the file the fleet writes, so the two cannot drift apart', async (): Promise<void> => {
+    const mosaicHome = await v2Home();
+    const rendered = (await conditionPath()).replace('%h', tempHome!).replace('%i', 'coder0');
+
+    // The path an installed fleet actually places for this agent.
+    expect(rendered).toBe(join(mosaicHome, 'fleet', 'agents', 'coder0.env.generated'));
+  });
+
+  it('guards a real failure — the launcher rejects an absent generated env', async (): Promise<void> => {
+    await v2Home();
+    await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
+
+    // Exactly what ExecStart runs, against the state the condition exists to
+    // catch: unit enabled, reconciler has not written env yet.
+    const launched = await new Promise<{ code: number | null; stderr: string }>((settle) => {
+      const child = execFile(
+        '/bin/bash',
+        [
+          '--noprofile',
+          '--norc',
+          join(tempHome!, '.config', 'mosaic', 'tools', 'fleet', 'start-agent-session.sh'),
+          'coder0',
+        ],
+        { env: { HOME: tempHome!, MOSAIC_AGENT_NAME: 'coder0', PATH: '/usr/bin:/bin' } },
+        (_error, _stdout, stderr) => {
+          settle({ code: child.exitCode, stderr });
+        },
+      );
+    });
+
+    expect(launched.code).not.toBe(0);
+    expect(launched.stderr).toContain('missing-file');
+  });
+});
+
+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);
+  });
+});

packages/mosaic/src/commands/fleet.ts

@@ -34,6 +34,7 @@ export {
   resolveInstalledFleetRosterPath,
 } from '../fleet/fleet-roster-v1.js';
 export type { FleetAgent, FleetRoster } from '../fleet/fleet-roster-v1.js';
+import { parseRosterV2 } from '../fleet/roster-v2.js';
 import {
   registerFleetAgentCrudCommands,
   type FleetAgentCrudCommandDeps,
@@ -820,7 +821,7 @@ export function buildEnableLingerCommand(user: string): string[] {
  */
 export async function enableFleetUnits(
   runner: CommandRunner,
-  roster: FleetRoster,
+  roster: { readonly agents: readonly { readonly name: string }[] },
   opts: { enable?: boolean },
 ): Promise<void> {
   if (opts.enable === false) {
@@ -1527,7 +1528,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
       await installFleet(cmd, frameworkRoot);
-      const roster = await loadRosterForCommand(cmd);
+      // Unit enablement needs agent names only, so it reads either version.
+      const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
     });
 
@@ -1537,7 +1539,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
       await installFleet(cmd, frameworkRoot);
-      const roster = await loadRosterForCommand(cmd);
+      // Unit enablement needs agent names only, so it reads either version.
+      const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
     });
 
@@ -1688,7 +1691,9 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .action(async (opts: { json?: boolean }) => {
       const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
       const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
-      const roster = await loadRosterForCommand(cmd);
+      // ps only reads, so it takes the version-agnostic read model rather than
+      // the v1 parser, which rejects a v2 roster outright.
+      const roster = await loadRosterReadModel(cmd);
       const { tenant_id, host } = getDefaultTenantAndHost();
       const nowMs = Date.now();
 
@@ -1908,6 +1913,16 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
           start: boolean;
         },
       ) => {
+        if (await usesRosterV2ControlPlane(cmd)) {
+          // command.error, not a bare throw: this is operator guidance, and a
+          // bare throw reaches the top level uncaught and prints it under a Node
+          // stack trace. Measured on canary — the message is the whole point of
+          // the refusal, so it has to arrive readable.
+          cmd.error(rosterV2MutationGuidance('add', 'create', name), {
+            code: 'fleet.roster-v2',
+            exitCode: 1,
+          });
+        }
         if (!VALID_FLEET_RUNTIMES.includes(opts.runtime)) {
           throw new Error(
             `Invalid runtime "${opts.runtime}". Valid runtimes: ${VALID_FLEET_RUNTIMES.join(', ')}.`,
@@ -1973,6 +1988,12 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Remove an agent from the fleet roster')
     .option('--keep-files', 'Skip deleting env and heartbeat files')
     .action(async (name: string, opts: { keepFiles?: boolean }) => {
+      if (await usesRosterV2ControlPlane(cmd)) {
+        cmd.error(rosterV2MutationGuidance('remove', 'delete', name), {
+          code: 'fleet.roster-v2',
+          exitCode: 1,
+        });
+      }
       const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
       const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
       const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
@@ -2331,7 +2352,9 @@ export function registerFleetAgentCommands(
 async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
   const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
   assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
-  const roster = await loadRosterForCommand(cmd);
+  // Read model first: every file this function places is roster-independent, and
+  // the v1 parser would reject a v2 roster before any of them were written.
+  const roster = await loadRosterReadModel(cmd);
   await ensureFleetHolderIdentity(activePaths.mosaicHome);
   await mkdir(activePaths.fleetToolsDir, { recursive: true });
   await mkdir(activePaths.tmuxToolsDir, { recursive: true });
@@ -2391,16 +2414,30 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
     join(activePaths.systemdUserDir, '[email protected]'),
   );
 
-  for (const agent of roster.agents) {
+  // On roster v2 the reconciler owns the generated env: `apply` writes it and
+  // `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
+  // here too — necessarily through the v1 mapping — would be the third writer of
+  // one file and would break the #791 single-SSOT invariant. So v2 gets the tool
+  // files and the units, and nothing else.
+  if (roster.version === 2) {
+    console.log(
+      `Installed fleet tools and systemd units for ${roster.agents.length} agent(s). ` +
+        `Generated env is owned by the reconciler on roster v2 — run: mosaic fleet apply --expected-generation <n>`,
+    );
+    return;
+  }
+
+  const v1Roster = await loadRosterForCommand(cmd);
+  for (const agent of v1Roster.agents) {
     await writeAgentEnvironmentProjection({
       mosaicHome: activePaths.mosaicHome,
       agentEnvDir: activePaths.agentEnvDir,
       agentName: agent.name,
-      generated: generateAgentEnvValues(roster, agent),
+      generated: generateAgentEnvValues(v1Roster, agent),
     });
   }
 
-  console.log(`Installed fleet files for ${roster.agents.length} agent(s).`);
+  console.log(`Installed fleet files for ${v1Roster.agents.length} agent(s).`);
 }
 
 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
@@ -2427,6 +2464,77 @@ async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
   );
 }
 
+/**
+ * `add`/`remove` and `create`/`delete` are not two spellings of one operation.
+ * The v1 pair edits the roster *and* drives systemd; the v2 pair is documented
+ * as changing desired state "without runtime actions", leaving convergence to
+ * `apply`. `add` also collects four fields where a v2 agent requires eleven, so
+ * routing it to `create` would mean inventing provider, alias, reasoning and
+ * tool-policy defaults on the operator's behalf. Refusing with the real command
+ * is honest; silently guessing an agent's provider is not.
+ */
+function rosterV2MutationGuidance(
+  v1Command: 'add' | 'remove',
+  v2Command: 'create' | 'delete',
+  name: string,
+): string {
+  const target = v2Command === 'delete' ? ` ${name}` : '';
+  return (
+    `mosaic fleet ${v1Command} does not operate on a roster-v2 fleet. ` +
+    `Roster v2 separates desired state from convergence:\n` +
+    `  1. mosaic fleet ${v2Command}${target} --expected-generation <current> ` +
+    `${v2Command === 'create' ? "--agent '<json>' " : ''}` +
+    `(edits the roster only)\n` +
+    `  2. mosaic fleet apply --expected-generation <new> (converges systemd and tmux)\n` +
+    `Read the current generation with: mosaic fleet status`
+  );
+}
+
+/**
+ * The read-only fields shared by roster v1 and v2, for the commands that only
+ * ever *read* the roster (`ps`, and unit enablement inside `install`).
+ *
+ * This is deliberately NOT a v2→v1 downshift. A downshifted `FleetRoster` would
+ * be accepted by `generateAgentEnvValues`, and that would make a third writer of
+ * `fleet/agents/<name>.env.generated` — through the v1 mapping — breaking the
+ * #791 single-SSOT invariant that {@link projectRosterV2AgentGeneratedEnv} is
+ * documented to hold. Keeping the read model this small makes that misuse
+ * impossible: there is nothing here to write a roster or an env file back from.
+ */
+interface FleetRosterReadModel {
+  readonly version: 1 | 2;
+  readonly tmux: { readonly socketName: string; readonly holderSession: string };
+  readonly agents: readonly {
+    readonly name: string;
+    readonly alias?: string;
+    readonly runtime: string;
+  }[];
+}
+
+/** Reads either roster version into the shared read-only view. */
+async function loadRosterReadModel(cmd: Command): Promise<FleetRosterReadModel> {
+  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
+  const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
+  if (!(await usesRosterV2ControlPlane(cmd))) {
+    const v1 = await loadRosterAtPath(cmd, path);
+    return {
+      version: 1,
+      tmux: { socketName: v1.tmux.socketName, holderSession: v1.tmux.holderSession },
+      agents: v1.agents,
+    };
+  }
+  try {
+    const v2 = parseRosterV2(await readFleetRosterText(path), 'yaml');
+    return {
+      version: 2,
+      tmux: { socketName: v2.tmux.socketName, holderSession: v2.tmux.holderSession },
+      agents: v2.agents,
+    };
+  } catch (error) {
+    reportFleetRosterConfigurationError(cmd, error);
+  }
+}
+
 async function loadRosterFromAgentCommand(
   command: Command,
   mosaicHomeOverride?: string,

tools/install.sh

@@ -390,6 +390,43 @@ ensure_prefix_on_path() {
   dim "  Run:  export PATH=\"$PREFIX/bin:\$PATH\"   (or start a new login shell)"
 }
 
+# Fleet transport binary (#1240).
+#
+# `mosaic fleet --help` reads "Manage the local Mosaic tmux fleet" and every
+# roster the CLI scaffolds sets `transport: tmux`, but nothing in this script
+# provides tmux and, until now, nothing in it mentioned tmux at all. A
+# greenfield host came out of this installer able to install a fleet, start a
+# fleet, and run no seat — the operator's first signal was `mosaic fleet ps`.
+#
+# Not a `require_cmd`: tmux is required by the fleet, not by mosaic. Plenty of
+# hosts install this to run `mosaic claude` and will never scaffold a roster,
+# and failing their install over a binary they do not need would be wrong. It
+# is a warning that names precisely what it blocks.
+#
+# `tools/_scripts/mosaic-doctor` carries a deliberately parallel check, so the
+# same host state gets the same answer from an audit as from an install. They
+# are separate implementations because this one has to work before the
+# framework's scripts are guaranteed to be on disk; keep their wording in step.
+check_fleet_transport() {
+  local transport=tmux
+  local roster="$MOSAIC_HOME/fleet/roster.yaml"
+  local declared=""
+
+  if [[ -f "$roster" ]]; then
+    declared="$(sed -n 's/^[[:space:]]*transport:[[:space:]]*//p' "$roster" | head -1 |
+      tr -d '"'\''' | tr -d '\r' | awk '{print $1}')"
+    [[ -n "$declared" ]] && transport="$declared"
+  fi
+
+  command -v "$transport" &>/dev/null && return 0
+
+  warn "Fleet transport '$transport' is not installed."
+  echo "  The Mosaic fleet runs its agent seats inside $transport. Without it,"
+  echo "  ${C}mosaic fleet start${RESET} reports success and no seat comes up."
+  echo "  Install it before using the fleet, e.g. ${C}sudo apt-get install -y $transport${RESET}"
+  echo "  (this does not affect ${C}mosaic claude${RESET} or the other single-runtime commands)."
+}
+
 installed_cli_version() {
   local json
   json="$(npm ls -g --depth=0 --json --prefix="$PREFIX" 2>/dev/null)" || true
@@ -1106,6 +1143,11 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
   ok "Done."
 fi
 
+# Fleet readiness (#1240). Runs in both normal and --check mode: "what is the
+# state of this host" is exactly the question --check is asked, and a host that
+# cannot run a seat should not have to discover it from `fleet ps`.
+check_fleet_transport
+
 } # end main
 
 main "$@"