fix(fleet): activate the lease broker at install/start, place units through symlinks safely, refuse doomed launches (#1292)

Wall 6: no documented path ever enabled or started the shipped
mosaic-lease-broker.service — every gated runtime died ~4s in at lease
registration while fleet start reported rc0, and a broker not in the
reconciler plan could not be reported as drifted.

Activation lands in the control plane, not the launcher:

- fleet install places ALL FOUR units through placeUnitFile — a placement
  helper that unlinks any by-path-enable symlink at the destination
  BEFORE copying (Node copyFile follows the link and overwrites the SEED
  template; measured on a throwaway systemd user instance 2026-08-17,
  with both cp and fs.copyFile), removes a stale wants-symlink pointing
  outside the active dir (readlink — readFile returns the target's
  content, not the link path), then copies and daemon-reloads. The same
  measurement showed systemctl enable <name> does NOT rewrite an existing
  by-path wants-symlink — reconciliation must be explicit. Idempotent:
  second install on by-path residue converges to the identical state.
  Until now the copy block named three units and omitted the broker, and
  the residue set / copy set were disjoint only by accident (fomo-lin
  survived copy-through because its one symlink was the one unit not
  copied); adding the broker made them intersect on first run. See the
  SET-INDEPENDENCE note on the helper before adding a fifth unit.
- enableFleetUnits enables the broker first, alongside the holder.
- fleet start / reconciler start the broker BEFORE any holder/agent
  lifecycle effect, then RE-CHECK the socket (not unit state) and exit
  nonzero with a named code if it did not appear. Re-probed on every
  invocation — a RemainAfterExit=yes dead-looking-active unit can never
  make retry look like repair (the sticky-retry check).
- The reconciler plan carries broker {unitInstalled, socketPresent} as a
  first-class member; the socket is the signal (enabled-but-dead units
  report socketPresent=false).
- start-agent-session.sh preflights the broker socket BEFORE any tmux
  effect (moved ahead of the ownership probe): absent -> exit 75
  (EX_TEMPFAIL), named refusal with socket path and remedy, no doomed
  pane. The agent@ unit is Type=oneshot with no Restart=, so the message
  survives instead of looping. The preflight detects and refuses; it
  never starts the broker.
- mosaic doctor's lease check names one convention-neutral remedy:
  'mosaic fleet install (it reconciles either enable convention)' —
  written from the measurement; teaching a manual systemctl line could
  leave a host with competing wants-symlinks.

Tests: fleet-place-unit.spec.ts (8: clean-host negative control,
by-path residue -> seed bytes AND mtime unchanged [the finding-2 check],
wants-residue cleared, idempotence single + double-install convergence);
fleet.spec.ts broker-first enable ordering, refused start emits no
holder/agent calls, second-start re-probe; reconciler broker plan member
(enabled-but-dead shape) + broker-before-agent ordering in both command
and apply paths; test-agent-session-broker-preflight.sh (CI-fit: fake
tmux, real unix socket at a short /tmp path — AF_UNIX caps at 108 bytes,
hermetic env; absent -> exit 75 + no tmux session, live socket passes,
explicit env wins, --stop not fenced). 1563/1563 vitest, lint, root
build 25/25, root typecheck 45/45.

Sabotage controls: placement unlink removed -> exactly the seed-integrity
test reddens (1/8); socket re-check disabled -> exactly the two preflight
specs redden; shell preflight removed -> the bash suite reddens (6 FAIL
assertions, rc=1). All restored byte-identically (sha256-verified), all
green again.

Test 6 (greenfield 1124, seat alive 2min + second fleet start) runs on
sandbox after daphne's baseline, coordinated with fred.

Note: the preflight uses exit 75 measured against the unit's Restart=
policy (oneshot, none) — no restart loop.

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

@@ -0,0 +1,253 @@
+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,8 +1,5 @@
-import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
+import { describe, it, expect } 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', () => {
@@ -78,162 +75,3 @@ 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,73 +1,5 @@
-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
@@ -92,14 +24,15 @@ export function registerMacpCommand(parent: Command): void {
       'Filter by task type (coding|deploy|research|review|documentation|infrastructure)',
     )
     .action((opts: { status?: string; type?: string }) => {
-      // unimplemented capability — a failure, never a success (RI-N2)
+      // not yet wired — task persistence layer is not present in @mosaicstack/macp
+      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}`);
       }
-      notImplemented('tasks list', 'task-persistence', 'use the macp package programmatically');
+      process.exitCode = 0;
     });
 
   // ─── submit ──────────────────────────────────────────────────────────────
@@ -108,11 +41,12 @@ export function registerMacpCommand(parent: Command): void {
     .command('submit <path>')
     .description('Submit a task from a JSON/YAML spec file')
     .action((specPath: string) => {
-      // unimplemented capability — a failure, never a success (RI-N2)
+      // not yet wired — task submission requires a running MACP server
+      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)');
-      notImplemented('submit', 'macp-server', 'use the macp package programmatically');
+      process.exitCode = 0;
     });
 
   // ─── gate ────────────────────────────────────────────────────────────────
@@ -124,58 +58,16 @@ 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')
-    .option(
+    .action((spec: string, opts: { failOn: string; cwd: string; log: string; timeout: string }) => {
-      '--simulate',
+      // not yet wired — gate execution requires a task context and event sink
-      'Simulate gates instead of executing them; results are typed simulated and never satisfy a check',
+      console.log('[macp] gate: not yet wired — use macp package programmatically');
-    )
+      console.log(`  spec:     ${spec}`);
-    .action(
+      console.log(`  fail-on:  ${opts.failOn}`);
-      (
+      console.log(`  cwd:      ${opts.cwd}`);
-        spec: string,
+      console.log(`  log:      ${opts.log}`);
-        opts: { failOn: string; cwd: string; log: string; timeout: string; simulate?: boolean },
+      console.log(`  timeout:  ${opts.timeout}s`);
-      ) => {
+      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 ──────────────────────────────────────────────────────────────
 
@@ -187,16 +79,14 @@ 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 }) => {
-      // unimplemented capability — a failure, never a success (RI-N2)
+      // not yet wired — event streaming requires a live event source
+      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');
       }
-      notImplemented('events tail', 'event-source', 'use the macp package programmatically');
+      process.exitCode = 0;
     });
 }
-
-// Re-export so CLI consumers can surface typed capability codes.
-export type { MacpErrorCode };

packages/macp/src/errors.ts

@@ -1,35 +0,0 @@
-/** 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

@@ -1,429 +0,0 @@
-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,20 +4,7 @@ import { dirname } from 'node:path';
 
 import { emitEvent } from './event-emitter.js';
 import { nowISO } from './event-emitter.js';
-import type { GateResult, GateStatus, RunGatesResult } from './types.js';
+import type { GateResult } 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;
@@ -116,91 +103,36 @@ 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 capabilityFailureResult(
+    return {
-      gateEntry,
+      command,
-      'MACP_NO_CI_PIPELINE',
+      exit_code: 0,
-      `ci-pipeline gate '${gateEntry.command || gateType}' has no CI provider implementation wired — refusing placeholder pass`,
+      type: gateType,
-    );
+      output: 'CI pipeline gate placeholder',
+      timed_out: false,
+      passed: true,
+    };
   }
 
   if (!command) {
-    // A manual gate with no automation waits for human sign-off: not pass, not fail.
+    return {
-    if (gateType === 'manual') {
+      command: '',
-      return waitingResult(
+      exit_code: 0,
-        gateEntry,
+      type: gateType,
-        `manual gate has no automation — waiting for human sign-off (type: ${gateType})`,
+      output: '',
-      );
+      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);
@@ -211,12 +143,10 @@ 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;
   }
 
@@ -240,7 +170,6 @@ 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;
@@ -262,19 +191,16 @@ export function runGates(
   timeoutSec: number,
   eventsPath: string,
   taskId: string,
-  options: RunGateOptions = {},
+): { allPassed: boolean; gateResults: GateResult[] } {
-): RunGatesResult {
+  let allPassed = true;
   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',
@@ -283,10 +209,10 @@ export function runGates(
       'quality-gate',
       `Running gate: ${label}`,
     );
-    const result = runGate(gate, cwd, logPath, timeoutSec, options);
+    const result = runGate(gate, cwd, logPath, timeoutSec);
     gateResults.push(result);
 
-    if (result.status === 'passed') {
+    if (result.passed) {
       emitEvent(
         eventsPath,
         'rail.check.passed',
@@ -298,46 +224,7 @@ export function runGates(
       continue;
     }
 
-    if (result.status === 'waiting') {
+    allPassed = false;
-      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}`;
@@ -349,15 +236,5 @@ export function runGates(
     emitEvent(eventsPath, 'rail.check.failed', taskId, 'gated', 'quality-gate', message);
   }
 
-  const state: GateStatus = hasCapabilityFailure
+  return { allPassed, gateResults };
-    ? 'capability_failure'
-    : hasSimulated
-      ? 'simulated'
-      : hasFailed
-        ? 'failed'
-        : hasWaiting
-          ? 'waiting'
-          : 'passed';
-
-  return { allPassed: state === 'passed', gateResults, state };
 }

packages/macp/src/index.ts

@@ -6,13 +6,11 @@ export type {
   DependsOnPolicy,
   GateType,
   GateFailOn,
-  GateStatus,
   GateEntry,
   Task,
   EventType,
   MACPEvent,
   GateResult,
-  RunGatesResult,
   TaskResult,
   ProviderMeta,
   ProviderRegistry,
@@ -20,11 +18,6 @@ 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,
@@ -42,16 +35,9 @@ export {
 export type { ResolveCredentialsOptions } from './credential-resolver.js';
 
 // Gate runner
-export {
+export { normalizeGate, runShell, countAIFindings, runGate, runGates } from './gate-runner.js';
-  normalizeGate,
-  runShell,
-  countAIFindings,
-  runGate,
-  runGates,
-  SIMULATED_GATE_REASON,
-} from './gate-runner.js';
 
-export type { NormalizedGate, RunGateOptions } from './gate-runner.js';
+export type { NormalizedGate } 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,5 +1,3 @@
-import type { MacpErrorCode } from './errors.js';
-
 /** Task status values. */
 export type TaskStatus = 'pending' | 'running' | 'gated' | 'completed' | 'failed' | 'escalated';
 
@@ -19,17 +17,7 @@ export type DispatchMode = 'yolo' | 'acp' | 'exec';
 export type DependsOnPolicy = 'all' | 'any' | 'all_terminal';
 
 /** Quality gate type. */
-export type GateType = 'mechanical' | 'ai-review' | 'ci-pipeline' | 'manual';
+export type GateType = 'mechanical' | 'ai-review' | 'ci-pipeline';
-
-/**
- * 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';
@@ -79,9 +67,7 @@ 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 {
@@ -102,14 +88,7 @@ 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;
@@ -117,22 +96,6 @@ 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/tools/fleet/start-agent-session.sh

@@ -233,8 +233,36 @@ assert_owned_tmux_server() {
     fail "tmux server ownership or environment validation failed"
 }
 
-# Validate exact server ownership before querying, cleaning, or creating any
+# Lease-broker socket preflight (#1292). The gated runtime (`mosaic yolo …` →
-# managed session. An unmanaged or contaminated named socket is never repaired.
+# launch-runtime.py) registers with the broker or dies ~4 seconds in, with the
+# diagnostic invisible because tmux destroys the dead pane. This check runs
+# BEFORE any tmux effect — including the ownership probe below — so a host
+# without a broker produces a named, surviving refusal instead of a doomed
+# pane. Exit 75 (EX_TEMPFAIL), distinct from 64 (bad projection) and 69 (host
+# not ready for other reasons); the agent@ unit is Type=oneshot with no
+# Restart=, so the failed unit keeps its message instead of looping. Socket
+# resolution matches launch.ts's defaultLeaseBrokerSocket precedence exactly.
+# This preflight DETECTS and REFUSES — it never starts the broker (activation
+# belongs to the fleet control plane; a component that both detects and fixes
+# cannot be used to measure whether the fix worked).
+broker_socket_path() {
+  if [ -n "${MOSAIC_LEASE_BROKER_SOCKET:-}" ]; then
+    printf '%s\n' "$MOSAIC_LEASE_BROKER_SOCKET"
+    return 0
+  fi
+  local runtime_dir="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+  printf '%s\n' "${runtime_dir}/mosaic-lease/broker.sock"
+}
+
+if [ "$MODE" = "launch" ]; then
+  _broker_socket=$(broker_socket_path)
+  if [ ! -S "$_broker_socket" ]; then
+    echo "[fleet] FAIL_LAUNCH broker-absent: lease broker socket ${_broker_socket} missing; runtime launch denied (#1292)." >&2
+    echo "[fleet] remedy: systemctl --user enable --now mosaic-lease-broker.service  (or reinstall via: mosaic fleet install)" >&2
+    exit 75
+  fi
+fi
+
 assert_owned_tmux_server
 
 if [ "$MODE" = interaction ]; then

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

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# CI-fit regression suite for the #1292 lease-broker socket preflight in
+# start-agent-session.sh.
+#
+# WHY THIS SUITE IS CI-FIT WHERE test-start-agent-session.sh IS NOT (#1017/#1270
+# context): that older suite's precondition is "the host does not have the pi
+# binary", which a CI image that ships pi violates — its guard correctly
+# refuses to report a pass there, so it is excluded from the chain. THIS suite
+# controls its own preconditions instead of inheriting them from the host: a
+# fake tmux on PATH, a fake mosaic on PATH, a real unix socket created in a
+# tmpdir, a hermetic env (env -i, fake HOME, GIT_CONFIG_GLOBAL severed). It
+# never depends on what the host has installed, so a green here means the same
+# thing on every host. Anyone adding cases: keep that property — no case may
+# depend on host state.
+#
+# The failure this suite is written down to catch (#1292): a seat launched on a
+# host with no lease broker dies ~4 seconds in at registration, with the
+# diagnostic invisible because tmux destroys the dead pane. The preflight runs
+# BEFORE any tmux effect and refuses with a NAMED code (exit 75, EX_TEMPFAIL)
+# so the message survives. The agent@ unit is Type=oneshot with no Restart=,
+# so a failed unit keeps its output instead of looping.
+#
+# Cases:
+#   1. absent socket -> exit 75, message names broker-absent + socket path +
+#      remedy, and NO tmux session was ever created (the doomed-pane half).
+#   2. present socket (real unix socket in tmpdir) -> proceeds PAST the
+#      preflight (the suite then stops at the next precondition, proving the
+#      preflight was not the refusal).
+#   3. explicit MOSAIC_LEASE_BROKER_SOCKET wins over XDG_RUNTIME_DIR default.
+#   4. --stop mode does NOT require the broker (teardown must not be fenced on
+#      a component whose absence is exactly what teardown may follow).
+#
+# Sabotage control, run by the developer (not in-suite): remove the preflight
+# block from start-agent-session.sh, re-run — case 1 fails (a tmux session is
+# created / exit is not 75), cases 2-4 still pass; restore byte-identically.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/agent-session-broker-preflight}"
+FAKE_HOME="$WORK_DIR/home"
+BIN_DIR="$WORK_DIR/bin"
+ENV_DIR="$WORK_DIR/env"
+SOCK_DIR="$WORK_DIR/sockets"
+LOG_FILE="$WORK_DIR/tmux-calls.log"
+
+rm -rf "$WORK_DIR"
+# The script asserts a managed directory tree under MOSAIC_HOME: mosaic/,
+# mosaic/fleet/, mosaic/fleet/agents/ — private (0700/0750-style) modes, no
+# symlinks — plus a per-agent env projection. Build the full tree the launcher
+# expects so the suite reaches the BROKER preflight rather than dying at
+# environment validation.
+mkdir -p "$FAKE_HOME/.config/mosaic/fleet/agents" "$BIN_DIR" "$SOCK_DIR"
+chmod 700 "$FAKE_HOME/.config/mosaic" "$FAKE_HOME/.config/mosaic/fleet/agents"
+chmod 750 "$FAKE_HOME/.config/mosaic/fleet"
+cat > "$FAKE_HOME/.config/mosaic/fleet/agents/preflight-test.env.generated" <<'ENVEOF'
+MOSAIC_AGENT_NAME=preflight-test
+MOSAIC_AGENT_CLASS=worker
+MOSAIC_AGENT_RUNTIME=pi
+MOSAIC_AGENT_MODEL=
+MOSAIC_AGENT_REASONING=
+MOSAIC_AGENT_TOOL_POLICY=code
+MOSAIC_AGENT_WORKDIR=/tmp
+MOSAIC_TMUX_SOCKET=mosaic-fleet
+ENVEOF
+chmod 600 "$FAKE_HOME/.config/mosaic/fleet/agents/preflight-test.env.generated"
+
+# ─── Fake tmux: records every invocation; new-session marks the marker. ────
+: > "$LOG_FILE"
+cat > "$BIN_DIR/tmux" <<SH
+#!/usr/bin/env bash
+printf 'tmux %s\n' "\$*" >> "$LOG_FILE"
+if [[ "\$*" == *new-session* ]]; then
+  echo "TMUX-NEW-SESSION-INVOKED" >> "$LOG_FILE"
+fi
+exit 0
+SH
+chmod +x "$BIN_DIR/tmux"
+
+# ─── Fake mosaic/pi binaries so the script proceeds past its own lookups. ───
+for bin in mosaic pi claude; do
+  printf '#!/usr/bin/env bash\nexit 0\n' > "$BIN_DIR/$bin"
+  chmod +x "$BIN_DIR/$bin"
+done
+
+# ─── Minimal launch environment the script expects. ────────────────────────
+# (Enough for the preflight to be reached; later stages will still fail in
+# case 2 — that is expected and asserted.)
+run_session_script() {
+  local mode="$1"; shift
+  (
+    cd "$WORK_DIR"
+    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:/usr/bin:/bin" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_HOME="$FAKE_HOME/.config/mosaic" \
+      AGENT_NAME=preflight-test \
+      "$@" \
+      bash "$SCRIPT_DIR/start-agent-session.sh" $mode preflight-test
+  )
+}
+
+fail=0
+assert() {
+  local desc="$1" expected="$2" actual="$3"
+  if [[ "$expected" != "$actual" ]]; then
+    echo "FAIL: $desc — expected '$expected', got '$actual'" >&2
+    fail=1
+  fi
+}
+assert_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  [[ "$haystack" == *"$needle"* ]] || { echo "FAIL: $desc — missing '$needle' in: $haystack" >&2; fail=1; }
+}
+assert_not_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "FAIL: $desc — must not contain '$needle'" >&2
+    fail=1
+  fi
+  return 0
+}
+
+# ─── 1. Absent socket → named refusal, NO tmux session. ────────────────────
+: > "$LOG_FILE"
+stderr_file="$WORK_DIR/stderr-1.tmp"
+set +e
+out=$(run_session_script "" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent.sock" 2>"$stderr_file")
+rc=$?
+set -e
+assert "absent socket exit code" "75" "$rc"
+err=$(cat "$stderr_file")
+assert_contains "absent socket names the failure" "$err" "FAIL_LAUNCH broker-absent"
+assert_contains "absent socket names the socket path" "$err" "$SOCK_DIR/absent.sock"
+assert_contains "absent socket names a remedy" "$err" "mosaic fleet install"
+log1=$(cat "$LOG_FILE")
+assert_not_contains "absent socket must not create a tmux session" "$log1" "TMUX-NEW-SESSION-INVOKED"
+
+# ─── 2. Present socket → passes the preflight. ─────────────────────────────
+# Expected: ownership/env checks AFTER the preflight may refuse (fixture is
+# minimal by design); the assertion is only that the refusal is NOT
+# broker-absent and the exit is NOT 75.
+# Create a REAL unix socket: a detached python holder binds it and stays alive
+# for the duration (bash cannot create sockets; a foreground python would
+# close the socket on exit and -S on a closed-but-unlinked path fails). Written
+# as a script file + setsid nohup so no job-control/heredoc interaction with
+# set -e can silently kill the suite.
+# AF_UNIX binds cap at 108 path bytes; the suite's workdir exceeds that, so
+# the live socket lives at a SHORT path under /tmp (unique per run, cleaned
+# with the suite). The preflight takes its socket path explicitly, so this
+# stays fully controlled.
+LIVE_SOCK=$(mktemp -u /tmp/mosaic-preflight-XXXXXX.sock)
+trap 'rm -f "$LIVE_SOCK"' EXIT
+rm -f "$SOCK_DIR/live.sock" "$LIVE_SOCK"
+cat > "$SOCK_DIR/holder.py" <<'PY'
+import socket, sys, time
+path = sys.argv[1]
+s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+s.bind(path)
+s.listen(1)
+time.sleep(120)
+PY
+python3 "$SOCK_DIR/holder.py" "$LIVE_SOCK" >/dev/null 2>"$SOCK_DIR/holder.err" &
+HOLDER_PID=$!
+# Wait for the socket object to exist (bind is near-instant, but do not race it).
+for _ in $(seq 1 50); do
+  [ -S "$LIVE_SOCK" ] && break
+  sleep 0.1
+done
+if [ ! -S "$LIVE_SOCK" ]; then
+  echo "FAIL: could not create live socket fixture (holder pid $HOLDER_PID)" >&2
+  ps -p "$HOLDER_PID" -o pid,stat,cmd --no-headers >&2 || echo "(holder exited)" >&2
+  cat "$SOCK_DIR/holder.err" >&2 || true
+  exit 1
+fi
+: > "$LOG_FILE"
+set +e
+out=$(run_session_script "" MOSAIC_LEASE_BROKER_SOCKET="$LIVE_SOCK" 2>"$WORK_DIR/stderr-2.tmp")
+rc=$?
+set -e
+# The preflight PASSED if the failure (whatever later stage refused) is NOT
+# the broker refusal, and tmux was reached or a later precondition named
+# something else.
+err2=$(cat "$WORK_DIR/stderr-2.tmp")
+assert_not_contains "live socket must not refuse broker-absent" "$err2" "broker-absent"
+if [[ "$rc" == "75" ]]; then
+  echo "FAIL: live socket — preflight still refused (exit 75) with a live socket" >&2
+  fail=1
+fi
+
+# ─── 3. Explicit socket env wins over XDG default. ─────────────────────────
+set +e
+out=$(run_session_script "" XDG_RUNTIME_DIR="$SOCK_DIR/no-runtime-here" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent2.sock" 2>"$WORK_DIR/stderr-3.tmp")
+rc=$?
+set -e
+assert "explicit env wins (exit 75)" "75" "$rc"
+assert_contains "explicit env path named" "$(cat "$WORK_DIR/stderr-3.tmp")" "$SOCK_DIR/absent2.sock"
+
+# ─── 4. --stop is not fenced on the broker. ────────────────────────────────
+: > "$LOG_FILE"
+set +e
+out=$(run_session_script "--stop" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent3.sock" 2>"$WORK_DIR/stderr-4.tmp")
+rc=$?
+set -e
+err4=$(cat "$WORK_DIR/stderr-4.tmp")
+assert_not_contains "--stop must not refuse broker-absent" "$err4" "broker-absent"
+if [[ "$rc" == "75" ]]; then
+  echo "FAIL: --stop — exit 75 means teardown was fenced on the broker" >&2
+  fail=1
+fi
+
+kill "$HOLDER_PID" 2>/dev/null || true
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "start-agent-session lease-broker preflight regression passed"
+fi
+exit "$fail"

packages/mosaic/src/commands/fleet-place-unit.spec.ts

@@ -0,0 +1,177 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { placeUnitFile, resolveLeaseBrokerSocketForPreflight } from './fleet.js';
+
+/**
+ * Unit-placement regression harness for #1292.
+ *
+ * The two measured defects this suite pins:
+ *  1. `systemctl enable <name>` does NOT rewrite an existing by-path
+ *     wants-symlink — so placement must remove stale residue explicitly, and
+ *     acceptance asserts on the RESULTING SYMLINK TARGET, never on the enable
+ *     call's argument (asserting the call cannot see where the link ended up).
+ *  2. Node's copyFile FOLLOWS a by-path symlink at the destination and
+ *     overwrites the SEED template. Acceptance asserts on the SEED's bytes
+ *     AND mtime — unchanged — which is the only check that can redden for
+ *     finding 2. The symlink-target assertion catches finding 1; these are
+ *     different defects with different failure modes.
+ *
+ * Fixtures are entirely inside tmpdirs (source template, active systemd dir,
+ * wants dir) — no real host paths are touched by this suite.
+ */
+
+describe('placeUnitFile (#1292 unit placement)', () => {
+  const cleanup: string[] = [];
+  afterEach(async () => {
+    while (cleanup.length > 0) {
+      await rm(cleanup.pop()!, { recursive: true, force: true });
+    }
+  });
+
+  async function fixture() {
+    const root = await mkdtemp(join(tmpdir(), 'place-unit-'));
+    cleanup.push(root);
+    const seedDir = join(root, 'seed');
+    const activeDir = join(root, 'active');
+    await mkdir(seedDir, { recursive: true });
+    await mkdir(activeDir, { recursive: true });
+    const seedTemplate = join(seedDir, 'unit-under-test.service');
+    await writeFile(
+      seedTemplate,
+      '[Unit]\nDescription=seed template\n[Service]\nType=oneshot\nExecStart=/bin/true\n[Install]\nWantedBy=default.target\n',
+    );
+    const activeSource = join(root, 'active-source.service');
+    await writeFile(
+      activeSource,
+      '[Unit]\nDescription=active copy v2\n[Service]\nType=oneshot\nExecStart=/bin/true\n[Install]\nWantedBy=default.target\n',
+    );
+    return { root, seedDir, activeDir, seedTemplate, activeSource };
+  }
+
+  it('places a regular file on a clean host (negative control: no residue anywhere)', async () => {
+    const f = await fixture();
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    expect(result.unlinkedDestinationSymlink).toBe(false);
+    expect(result.removedStaleWantsSymlink).toBe(false);
+    const info = await lstat(join(f.activeDir, 'unit-under-test.service'));
+    expect(info.isSymbolicLink()).toBe(false);
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toContain(
+      'active copy v2',
+    );
+    // Seed untouched by construction — but assert it, so the clean-host case
+    // cannot silently regress into seed-mutation.
+    expect(await readFile(f.seedTemplate, 'utf8')).toContain('seed template');
+  });
+
+  it('by-path residue: unlinks destination symlink, places the file, seed bytes AND mtime unchanged (finding 2)', async () => {
+    const f = await fixture();
+    const seedBefore = await readFile(f.seedTemplate, 'utf8');
+    const mtimeBefore = (await lstat(f.seedTemplate)).mtimeMs;
+    // The fomo-lin convention: by-path enable left a symlink AT the unit name
+    // pointing at the seed template, plus a wants-symlink doing the same.
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    expect(result.unlinkedDestinationSymlink).toBe(true);
+    expect(result.removedStaleWantsSymlink).toBe(true);
+
+    // FINDING 2's check: the seed is byte-identical and its mtime did not move.
+    expect(await readFile(f.seedTemplate, 'utf8')).toBe(seedBefore);
+    expect((await lstat(f.seedTemplate)).mtimeMs).toBe(mtimeBefore);
+
+    // The destination is now a regular file carrying the ACTIVE content.
+    const destInfo = await lstat(join(f.activeDir, 'unit-under-test.service'));
+    expect(destInfo.isSymbolicLink()).toBe(false);
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toContain(
+      'active copy v2',
+    );
+  });
+
+  it('by-path residue: no wants-symlink remains pointing at the seed (finding 1 residue cleared)', async () => {
+    const f = await fixture();
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+
+    // After placement the stale wants link is GONE (enable-by-name recreates
+    // it correctly). A link still present must not point at the seed.
+    try {
+      const link = await lstat(join(wantsDir, 'unit-under-test.service'));
+      if (link.isSymbolicLink()) {
+        const target = await readFile(join(wantsDir, 'unit-under-test.service'), 'utf8').catch(
+          async () => '',
+        );
+        expect(target).not.toContain('seed template');
+      }
+    } catch {
+      // absent wants link — the expected post-placement state
+    }
+  });
+
+  it('idempotence: second placement on a reconciled host is a no-op producing the identical final state', async () => {
+    const f = await fixture();
+    // Reconciled starting state: regular file at the name, wants link to the active copy.
+    await writeFile(
+      join(f.activeDir, 'unit-under-test.service'),
+      await readFile(f.activeSource, 'utf8'),
+    );
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(
+      join(f.activeDir, 'unit-under-test.service'),
+      join(wantsDir, 'unit-under-test.service'),
+    );
+    const before = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    // No destructive step fired: no unlink, no wants removal.
+    expect(result.unlinkedDestinationSymlink).toBe(false);
+    expect(result.removedStaleWantsSymlink).toBe(false);
+    // Identical final state.
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toBe(before);
+    const link = await lstat(join(wantsDir, 'unit-under-test.service'));
+    expect(link.isSymbolicLink()).toBe(true);
+  });
+
+  it('double install on by-path residue converges to the identical reconciled state', async () => {
+    const f = await fixture();
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    const first = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+    const secondRun = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    const second = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+    expect(secondRun.unlinkedDestinationSymlink).toBe(false);
+    expect(second).toBe(first);
+  });
+});
+
+describe('resolveLeaseBrokerSocketForPreflight (#1292 preflight resolution)', () => {
+  it('explicit MOSAIC_LEASE_BROKER_SOCKET wins', () => {
+    expect(
+      resolveLeaseBrokerSocketForPreflight({ MOSAIC_LEASE_BROKER_SOCKET: '/custom/sock' }, 1000),
+    ).toBe('/custom/sock');
+  });
+  it('XDG_RUNTIME_DIR next', () => {
+    expect(resolveLeaseBrokerSocketForPreflight({ XDG_RUNTIME_DIR: '/run/user/1001' }, 1000)).toBe(
+      '/run/user/1001/mosaic-lease/broker.sock',
+    );
+  });
+  it('falls back to /run/user/<uid>', () => {
+    expect(resolveLeaseBrokerSocketForPreflight({}, 1002)).toBe(
+      '/run/user/1002/mosaic-lease/broker.sock',
+    );
+  });
+});

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

@@ -835,13 +835,25 @@ describe('fleet command construction', () => {
     };
     const program = new Command();
     program.exitOverride();
-    registerFleetCommand(program, { runner, mosaicHome: home });
+    // #1292: inject a present broker socket so the preflight passes and this
+    // spec keeps testing its ORIGINAL property (holder-before-agent ordering).
+    // The preflight's own refusal behavior has dedicated specs below.
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => true,
+    });
 
     try {
       await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
       await program.parseAsync(['node', 'mosaic', 'fleet', 'stop']);
 
       expect(calls).toEqual([
+        // #1292: fleet start enables + starts the broker FIRST (enable is
+        // idempotent; the unit exists after install), re-checking the socket
+        // before any holder/agent lifecycle effect.
+        ['systemctl', '--user', 'enable', 'mosaic-lease-broker.service'],
+        ['systemctl', '--user', 'start', 'mosaic-lease-broker.service'],
         ['systemctl', '--user', 'start', 'mosaic-tmux-holder.service'],
         ['systemctl', '--user', 'start', '[email protected]'],
         ['systemctl', '--user', 'stop', '[email protected]'],
@@ -852,6 +864,92 @@ describe('fleet command construction', () => {
     }
   });
 
+  it('fleet start refuses with a named error when the broker socket does not appear (#1292)', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    await mkdir(join(home, 'fleet'), { recursive: true });
+    await writeFile(
+      rosterPath,
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
+        '\n',
+      ),
+    );
+    const calls: string[][] = [];
+    const runner: CommandRunner = async (command, args) => {
+      calls.push([command, ...args]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    };
+    const program = new Command();
+    program.exitOverride();
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.join(' '));
+    };
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => false,
+    });
+    try {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      // Refused: no holder/agent starts were issued after the broker attempt.
+      expect(calls).toEqual([
+        ['systemctl', '--user', 'enable', 'mosaic-lease-broker.service'],
+        ['systemctl', '--user', 'start', 'mosaic-lease-broker.service'],
+      ]);
+      expect(errors.join('\n')).toContain('broker-absent');
+      expect(errors.join('\n')).toContain('mosaic fleet install');
+    } finally {
+      console.error = origError;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('fleet start re-probes the broker on the SECOND invocation — no ActiveState trust (#1292 sticky half)', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    await mkdir(join(home, 'fleet'), { recursive: true });
+    await writeFile(
+      rosterPath,
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
+        '\n',
+      ),
+    );
+    const calls: string[][] = [];
+    const runner: CommandRunner = async (command, args) => {
+      calls.push([command, ...args]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    };
+    const program = new Command();
+    program.exitOverride();
+    // Broker socket NEVER appears — the second start must refuse exactly like
+    // the first; RemainAfterExit-style stale unit state changes nothing
+    // because the check is the socket, not systemctl.
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => false,
+    });
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.join(' '));
+    };
+    try {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      // Two invocations, each refusing after its own broker attempt:
+      expect(
+        calls.filter((c) => c.join(' ') === 'systemctl --user start [email protected]'),
+      ).toHaveLength(0);
+      expect(errors.filter((e) => e.includes('broker-absent')).length).toBeGreaterThanOrEqual(2);
+    } finally {
+      console.error = origError;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
   it('waits for an in-flight restart to clear before relaunching (re-entry guard)', async () => {
     const home = await tempDir();
     const rosterPath = join(home, 'fleet', 'roster.yaml');
@@ -2065,8 +2163,19 @@ describe('fleet install — auto-enable units for boot-survival', () => {
 
     await enableFleetUnits(runner, minimalRoster, {});
 
+    expect(calls).toContainEqual(['systemctl', '--user', 'enable', 'mosaic-lease-broker.service']);
     expect(calls).toContainEqual(['systemctl', '--user', 'enable', 'mosaic-tmux-holder.service']);
     expect(calls).toContainEqual(['systemctl', '--user', 'enable', '[email protected]']);
+    // The broker must be enabled BEFORE the holder and agents: a start of any
+    // gated runtime without the broker is exactly the #1292 4-second death.
+    const brokerIndex = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-lease-broker.service',
+    );
+    const holderIndex = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-tmux-holder.service',
+    );
+    expect(brokerIndex).toBeGreaterThanOrEqual(0);
+    expect(brokerIndex).toBeLessThan(holderIndex);
   });
 
   it('install still succeeds when systemctl enable returns non-zero (non-fatal)', async () => {

packages/mosaic/src/commands/fleet.ts

@@ -3,9 +3,11 @@ import {
   access,
   chmod,
   copyFile,
+  lstat,
   mkdir,
   open,
   readFile,
+  readlink,
   stat,
   unlink,
   writeFile,
@@ -89,6 +91,8 @@ export type SleepFn = (ms: number) => Promise<void>;
 
 export interface FleetCommandDeps {
   runner?: CommandRunner;
+  /** Test seam for the #1292 fleet-start broker preflight (socket presence). */
+  checkBrokerSocket?: (path: string) => Promise<boolean> | boolean;
   /** Injectable interactive runner for commands needing inherited TTY (e.g., `tmux attach`). */
   interactiveRunner?: InteractiveRunner;
   /**
@@ -797,6 +801,96 @@ export function buildSystemdEnableCommand(unit: string): string[] {
   return ['systemctl', '--user', 'enable', unit];
 }
 
+/**
+ * Place a unit file into the ACTIVE systemd user directory, never through a
+ * symlink (#1292, measured 2026-08-17).
+ *
+ * ⚠ SET-INDEPENDENCE (fomo-lin, 2026-08-17): the set of unit names carrying
+ * by-path residue and the set of unit names this install copies are
+ * INDEPENDENT. Until 0.0.50 they were disjoint only by accident of which
+ * units the install happened to name — fomo-lin survived copy-through solely
+ * because its one by-path symlink (the broker) was the one unit the install
+ * did NOT copy. Adding the broker to the copy set made the intersection
+ * non-empty on the first run. Whoever adds a fifth unit to the placement
+ * list inherits this helper and its unlink step; do not place units with a
+ * bare copyFile.
+ *
+ * A host provisioned by the enable-by-path convention carries a symlink AT
+ * the unit-name path in ~/.config/systemd/user/ pointing at the shipped
+ * template under ~/.config/mosaic/systemd/user/. Node's copyFile FOLLOWS
+ * that link and overwrites the SEED template instead of placing the active
+ * unit (verified with fs.copyFile on a throwaway systemd user instance) —
+ * silent, rc=0, and it mutates the directory every later reseed reads from.
+ * The same measurement showed `systemctl enable <name>` does NOT rewrite an
+ * existing by-path wants-symlink, so reconciliation must be explicit.
+ *
+ * Placement therefore: if the destination is a symlink, unlink it first
+ * (unlink → copy — copy-then-unlink would mutate the seed and then destroy
+ * the evidence that it did); then copy. Also removes a stale
+ * `default.target.wants/<name>` symlink that points outside the active
+ * directory (readlink — NOT readFile, which follows the link and returns the
+ * target's CONTENT), so the subsequent enable-by-name recreates it against
+ * the active copy. Idempotent: on a clean or already-reconciled destination
+ * every step is a no-op (the copy rewrites identical bytes).
+ *
+ * Returns what was done, for assertions and install reporting.
+ */
+export interface PlaceUnitResult {
+  readonly unit: string;
+  readonly destination: string;
+  /** A symlink at the unit-name path was unlinked (by-path residue). */
+  readonly unlinkedDestinationSymlink: boolean;
+  /** A stale wants-symlink pointing outside the active dir was removed. */
+  readonly removedStaleWantsSymlink: boolean;
+}
+
+export async function placeUnitFile(
+  source: string,
+  systemdUserDir: string,
+  unit: string,
+): Promise<PlaceUnitResult> {
+  const destination = join(systemdUserDir, unit);
+  let unlinkedDestinationSymlink = false;
+  try {
+    const destInfo = await lstat(destination);
+    if (destInfo.isSymbolicLink()) {
+      await unlink(destination);
+      unlinkedDestinationSymlink = true;
+    }
+  } catch {
+    // absent destination — nothing to unlink
+  }
+  await copyFile(source, destination);
+
+  let removedStaleWantsSymlink = false;
+  const wantsLink = join(systemdUserDir, 'default.target.wants', unit);
+  try {
+    const wantsInfo = await lstat(wantsLink);
+    if (wantsInfo.isSymbolicLink()) {
+      // readlink — NOT readFile: readFile FOLLOWS the link and returns the
+      // target file's CONTENT, which is not the question being asked.
+      let target: string | undefined;
+      try {
+        target = await readlink(wantsLink);
+      } catch {
+        target = undefined;
+      }
+      // Normalize (systemctl writes absolute targets; a relative one resolves
+      // against the wants dir). A wants-symlink pointing anywhere other than
+      // the active copy (the by-path convention points at the seed template)
+      // survives enable-by-name unchanged — remove it so enable recreates it.
+      if (target !== undefined && resolve(dirname(wantsLink), target) !== destination) {
+        await unlink(wantsLink);
+        removedStaleWantsSymlink = true;
+      }
+    }
+  } catch {
+    // absent wants link — nothing to reconcile
+  }
+
+  return { unit, destination, unlinkedDestinationSymlink, removedStaleWantsSymlink };
+}
+
 /**
  * Returns the systemctl --user disable command for a given unit.
  * Used by `fleet remove` so a removed agent's enabled unit cannot resurrect on
@@ -831,6 +925,22 @@ export async function enableFleetUnits(
     let succeeded = 0;
     let failed = 0;
 
+    // The lease broker ships with the fleet and every gated runtime needs it
+    // (#1292): seats die at lease registration without it, and no documented
+    // path ever enabled it. Enabled first — alongside the holder — and the
+    // unit must have been placed by installFleet's placeUnitFile step.
+    const brokerResult = await runner(
+      ...splitCommand(buildSystemdEnableCommand('mosaic-lease-broker.service')),
+    );
+    if (brokerResult.exitCode === 0) {
+      succeeded++;
+    } else {
+      failed++;
+      process.stderr.write(
+        `Warning: could not enable mosaic-lease-broker.service: ${brokerResult.stderr || brokerResult.stdout || 'non-zero exit'}\n`,
+      );
+    }
+
     const holderResult = await runner(
       ...splitCommand(buildSystemdEnableCommand('mosaic-tmux-holder.service')),
     );
@@ -1527,7 +1637,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot);
+      await installFleet(cmd, frameworkRoot, runner);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1538,7 +1648,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot);
+      await installFleet(cmd, frameworkRoot, runner);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1591,6 +1701,37 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
             );
             return;
           }
+          if (action === 'start') {
+            // Broker preflight (#1292), re-probed on EVERY invocation: a
+            // gated runtime started without a live lease broker dies ~4s in
+            // while the unit reports active (RemainAfterExit) — enabling +
+            // starting here and then RE-CHECKING the socket refuses loudly
+            // instead of reporting rc0 over a doomed start. This is the
+            // second-start check as much as the first: it never trusts unit
+            // ActiveState.
+            await runChecked(runner, [
+              'systemctl',
+              '--user',
+              'enable',
+              'mosaic-lease-broker.service',
+            ]);
+            await runChecked(runner, [
+              'systemctl',
+              '--user',
+              'start',
+              'mosaic-lease-broker.service',
+            ]);
+            if (!(await brokerSocketPresent(deps))) {
+              console.error(
+                '[fleet] broker-absent: lease broker socket did not appear after enable+start (#1292).',
+              );
+              console.error(
+                '[fleet] remedy: mosaic fleet install (it reconciles either enable convention)',
+              );
+              process.exitCode = 1;
+              return;
+            }
+          }
           if (action === 'restart') {
             // Serialize the holder+agents teardown/relaunch behind the restart lock
             // so a re-entrant restart waits for clean shutdown before relaunching,
@@ -2349,7 +2490,11 @@ export function registerFleetAgentCommands(
     });
 }
 
-async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
+async function installFleet(
+  cmd: Command,
+  frameworkRoot: string,
+  runner: CommandRunner,
+): Promise<void> {
   const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
   assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
   // Read model first: every file this function places is roster-independent, and
@@ -2401,18 +2546,40 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
   for (const toolPath of executableToolPaths) {
     await chmod(toolPath, 0o755);
   }
-  await copyFile(
+  // Unit placement (#1292): every unit goes through placeUnitFile — never a
-    join(frameworkRoot, 'systemd', 'user', 'mosaic-tmux-holder.service'),
+  // bare copyFile — so a by-path-enable symlink at the destination is
-    join(activePaths.systemdUserDir, 'mosaic-tmux-holder.service'),
+  // unlinked rather than written through (copy-through would silently
+  // overwrite the SEED template, measured 2026-08-17). The lease broker unit
+  // is placed here too: previously the install named three units and omitted
+  // the broker entirely, which is why no documented path ever enabled it.
+  const placedUnits = await Promise.all(
+    [
+      'mosaic-tmux-holder.service',
+      '[email protected]',
+      '[email protected]',
+      'mosaic-lease-broker.service',
+    ].map((unit) =>
+      placeUnitFile(join(frameworkRoot, 'systemd', 'user', unit), activePaths.systemdUserDir, unit),
+    ),
   );
-  await copyFile(
+  const reconciled = placedUnits.filter(
-    join(frameworkRoot, 'systemd', 'user', '[email protected]'),
+    (result) => result.unlinkedDestinationSymlink || result.removedStaleWantsSymlink,
-    join(activePaths.systemdUserDir, '[email protected]'),
-  );
-  await copyFile(
-    join(frameworkRoot, 'systemd', 'user', '[email protected]'),
-    join(activePaths.systemdUserDir, '[email protected]'),
   );
+  if (reconciled.length > 0) {
+    console.log(
+      `Reconciled ${reconciled.length} unit placement(s) from by-path enable residue: ${reconciled.map((r) => r.unit).join(', ')}`,
+    );
+  }
+  // systemd will not see a replaced unit file without a reload; do it once
+  // after all placements, before any enable call below. runCommand never
+  // rejects (it resolves exitCode 127 on spawn error), so a plain await with
+  // an exitCode check matches the rest of this file's systemctl handling.
+  const reloadResult = await runner(...splitCommand(['systemctl', '--user', 'daemon-reload']));
+  if (reloadResult.exitCode !== 0) {
+    process.stderr.write(
+      `Warning: systemctl --user daemon-reload after unit placement failed (non-systemd host?): ${reloadResult.stderr || reloadResult.stdout || 'non-zero exit'}\n`,
+    );
+  }
 
   // On roster v2 the reconciler owns the generated env: `apply` writes it and
   // `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
@@ -2609,6 +2776,40 @@ function splitCommand(command: string[]): [string, string[]] {
   return [bin, args];
 }
 
+/**
+ * Lease-broker socket presence for the fleet-start preflight (#1292).
+ * Resolution precedence matches launch.ts's defaultLeaseBrokerSocket and
+ * start-agent-session.sh's broker_socket_path: explicit
+ * MOSAIC_LEASE_BROKER_SOCKET, else $XDG_RUNTIME_DIR/mosaic-lease/broker.sock,
+ * else /run/user/<uid>/mosaic-lease/broker.sock. Pure filesystem check — this
+ * deliberately does NOT consult systemd state: a unit can be active
+ * (RemainAfterExit) with no live socket, and the socket is the thing the
+ * gated runtime connects to. Injectable via deps for tests.
+ */
+export function resolveLeaseBrokerSocketForPreflight(
+  env: NodeJS.ProcessEnv = process.env,
+  uid: number = typeof process.getuid === 'function' ? process.getuid() : 0,
+): string {
+  if (env['MOSAIC_LEASE_BROKER_SOCKET']) return env['MOSAIC_LEASE_BROKER_SOCKET'];
+  const runtimeDir = env['XDG_RUNTIME_DIR'] ?? `/run/user/${uid}`;
+  return join(runtimeDir, 'mosaic-lease', 'broker.sock');
+}
+
+async function brokerSocketPresent(
+  deps: FleetCommandDeps,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<boolean> {
+  const check = deps.checkBrokerSocket;
+  if (check) return check(resolveLeaseBrokerSocketForPreflight(env));
+  try {
+    const socketPath = resolveLeaseBrokerSocketForPreflight(env);
+    await access(socketPath, constants.S_IFSOCK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** All supported fleet profile names. */
 export type FleetProfile =
   | 'general'

packages/mosaic/src/commands/lease-doctor-check.ts

@@ -205,6 +205,12 @@ export async function runLeaseEnforcementDoctorCheck(
     message:
       `Lease-enforcement hooks (${matchedMarkers.join(', ')}) are wired in ~/.claude/settings.json, but ${reasons.join(' and ')}. ` +
       'Every gated tool call will fail closed and BRICK this agent (see #869). ' +
-      'Remediate by activating the lease-broker supervisor (systemd unit + socket) or by removing the enforcement hooks from ~/.claude/settings.json.',
+      // #1292: one remedy, correct under BOTH enable conventions (by-path on
+      // the seed template, and copy-then-enable in the active dir). Written
+      // from the 2026-08-17 symlink measurement: `systemctl enable` by name
+      // does NOT rewrite an existing by-path wants-symlink, so teaching a
+      // manual systemctl line here could leave a host with two competing
+      // wants links. fleet install reconciles either shape.
+      'Remedy: run `mosaic fleet install` (it reconciles either enable convention), or remove the enforcement hooks from ~/.claude/settings.json.',
   };
 }

packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts

@@ -459,6 +459,7 @@ describe('FCM-M3-002 reconciler lifecycle acceptance', (): void => {
       plan: {
         generation: 7,
         holder: 'owned',
+        broker: { unitInstalled: false, socketPresent: false },
         agents: [
           {
             name: 'coder0',

packages/mosaic/src/fleet/fleet-reconciler.spec.ts

@@ -92,6 +92,112 @@ async function run(command: FleetReconcileCommand, overrides: Partial<FleetRecon
 }
 
 describe('fleet roster-owned reconciler', (): void => {
+  // ── #1292: broker as first-class plan member + broker-first start ordering ──
+
+  it('reports broker unit and socket state in the plan (socket is the signal, not unit state)', async (): Promise<void> => {
+    const result = await run('status', {
+      statPath: async () => true,
+      checkBrokerSocket: async () => true,
+    });
+    expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: true });
+  });
+
+  it('reports a dead broker as socketPresent=false even when the unit is installed (enabled-but-dead is the #1292 shape)', async (): Promise<void> => {
+    const result = await run('status', {
+      statPath: async () => true,
+      checkBrokerSocket: async () => false,
+    });
+    expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: false });
+  });
+
+  it('reports broker-absent when neither seam is present (defaults false, never guesses healthy)', async (): Promise<void> => {
+    const result = await run('status');
+    expect(result.plan.broker).toEqual({ unitInstalled: false, socketPresent: false });
+  });
+
+  it('command start enables and starts the broker BEFORE the holder and any agent unit', async (): Promise<void> => {
+    const calls: string[][] = [];
+    const result = await run('start', {
+      runner: async (command, args) => {
+        calls.push([command, ...args]);
+        if (command === 'tmux' && args.includes('list-sessions')) {
+          return { stdout: '_holder\ncoder0\n', stderr: '', exitCode: 0 };
+        }
+        if (command === 'tmux' && args.includes('show-environment')) {
+          return {
+            stdout:
+              'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    });
+    expect(result.lifecycle).toBe('complete');
+    const brokerEnable = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-lease-broker.service',
+    );
+    const brokerStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-lease-broker.service',
+    );
+    const holderStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-tmux-holder.service',
+    );
+    const agentStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(brokerEnable).toBeGreaterThanOrEqual(0);
+    expect(brokerStart).toBeGreaterThan(brokerEnable);
+    // Holder start may be absent (holder 'owned' in this fixture); if present it must follow the broker.
+    if (holderStart >= 0) expect(holderStart).toBeGreaterThan(brokerStart);
+    expect(agentStart).toBeGreaterThan(brokerStart);
+  });
+
+  it('apply with a running desired agent also enables and starts the broker first', async (): Promise<void> => {
+    const calls: string[][] = [];
+    const runningRoster: FleetRosterV2 = {
+      ...roster,
+      agents: roster.agents.map((agent) =>
+        agent.name === 'coder0'
+          ? { ...agent, lifecycle: { enabled: true, desiredState: 'running' as const } }
+          : agent,
+      ),
+    };
+    const result = await executeFleetReconcile({
+      roster: runningRoster,
+      command: 'apply',
+      expectedGeneration: 7,
+      deps: deps({
+        readRoster: async () => runningRoster,
+        runner: async (command, args) => {
+          calls.push([command, ...args]);
+          if (command === 'tmux' && args.includes('list-sessions')) {
+            return { stdout: '_holder\n', stderr: '', exitCode: 0 };
+          }
+          if (command === 'tmux' && args.includes('show-environment')) {
+            return {
+              stdout:
+                'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+              stderr: '',
+              exitCode: 0,
+            };
+          }
+          return { stdout: '', stderr: '', exitCode: 0 };
+        },
+      }),
+    });
+    expect(result.applied).toBe(true);
+    const brokerStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-lease-broker.service',
+    );
+    const agentStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(brokerStart).toBeGreaterThanOrEqual(0);
+    expect(agentStart).toBeGreaterThan(brokerStart);
+  });
+
   it('fails closed on a symlinked fleet ancestor without touching its target', async (): Promise<void> => {
     const home = await lockHome();
     const fleet = join(home, 'fleet');

packages/mosaic/src/fleet/fleet-reconciler.ts

@@ -43,6 +43,10 @@ export interface FleetReconcileDeps {
   readonly overrideDir?: string;
   readonly homeDirectory?: string;
   readonly readHolderIdentity?: () => Promise<string>;
+  /** Test/observation seams for the lease-broker plan member (#1292). */
+  readonly statPath?: (path: string) => Promise<boolean> | boolean;
+  readonly checkBrokerSocket?: (path: string) => Promise<boolean> | boolean;
+  readonly brokerSocketEnv?: NodeJS.ProcessEnv;
   readonly validateRoster?: (roster: FleetRosterV2) => Promise<void>;
   readonly prepareProjections?: (roster: FleetRosterV2) => Promise<readonly unknown[]>;
   readonly applyProjection?: (prepared: unknown) => Promise<unknown>;
@@ -74,6 +78,17 @@ export interface FleetReconcileObservedAgent {
 export interface FleetReconcilePlan {
   readonly generation: number;
   readonly holder: 'owned' | 'missing' | 'ownership-mismatch';
+  /**
+   * Lease broker observation (#1292): every gated runtime registers with the
+   * broker or dies ~4s in — a broker not in the plan cannot be reported as
+   * drifted, which made "broker died an hour ago" and "broker fine"
+   * produce identical output. `unitInstalled` = unit file present in the
+   * active dir; `socketPresent` = live broker at the resolved socket path.
+   */
+  readonly broker: {
+    readonly unitInstalled: boolean;
+    readonly socketPresent: boolean;
+  };
   readonly agents: readonly FleetReconcileObservedAgent[];
   readonly unmanagedSessions: readonly string[];
 }
@@ -314,6 +329,39 @@ function isObservational(command: FleetReconcileCommand): boolean {
   return command === 'plan' || command === 'status' || command === 'verify' || command === 'doctor';
 }
 
+/**
+ * Observe the lease broker for the plan (#1292). Unit presence via systemctl
+ * is-system-running is NOT the signal — a unit can be enabled-but-dead. The
+ * authoritative signal is the socket the gated runtimes connect to, matching
+ * broker-supervisor.ts's `checkBrokerSupervisorHealth` (healthy ===
+ * socketPresent). Injectable so tests drive every branch without a broker.
+ */
+async function observeBroker(deps: FleetReconcileDeps): Promise<FleetReconcilePlan['broker']> {
+  const homeDirectory = deps.homeDirectory ?? homedir();
+  const env = (deps.brokerSocketEnv ?? process.env) as NodeJS.ProcessEnv;
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+  const runtimeDir = env['XDG_RUNTIME_DIR'] ?? `/run/user/${uid}`;
+  const socketPath =
+    env['MOSAIC_LEASE_BROKER_SOCKET'] ?? join(runtimeDir, 'mosaic-lease', 'broker.sock');
+  const configHome = env['XDG_CONFIG_HOME'] ?? join(homeDirectory, '.config');
+  const unitPath = join(configHome, 'systemd', 'user', 'mosaic-lease-broker.service');
+  const statPath = deps.statPath;
+  const checkBrokerSocket = deps.checkBrokerSocket;
+  let unitInstalled = false;
+  let socketPresent = false;
+  try {
+    unitInstalled = statPath ? await statPath(unitPath) : false;
+  } catch {
+    unitInstalled = false;
+  }
+  try {
+    socketPresent = checkBrokerSocket ? await checkBrokerSocket(socketPath) : false;
+  } catch {
+    socketPresent = false;
+  }
+  return { unitInstalled, socketPresent };
+}
+
 async function observeFleet(
   roster: FleetRosterV2,
   deps: FleetReconcileDeps,
@@ -324,10 +372,12 @@ async function observeFleet(
     '-F',
     '#{session_name}',
   ]);
+  const broker = await observeBroker(deps);
   if (sessionsResult.exitCode !== 0) {
     return {
       generation: roster.generation,
       holder: 'missing',
+      broker,
       agents: await observeAgents(roster, deps, new Set<string>()),
       unmanagedSessions: [],
     };
@@ -350,6 +400,7 @@ async function observeFleet(
   return {
     generation: roster.generation,
     holder,
+    broker,
     agents: await observeAgents(roster, deps, sessions),
     unmanagedSessions: Object.freeze(unmanagedSessions.sort()),
   };
@@ -517,6 +568,24 @@ async function executeExplicitLifecycle(
     }
   }
   try {
+    // Broker FIRST (#1292): a gated runtime started without a running lease
+    // broker dies ~4 seconds in at registration — enable the unit (install
+    // places it) and start it before any holder/agent lifecycle effect. The
+    // socket re-check after start is the same probe observeBroker uses, so a
+    // unit that starts but never produces a socket is caught here, not four
+    // seconds later inside a doomed seat.
+    if (request.command === 'start') {
+      await runChecked(request.deps, 'systemctl', [
+        '--user',
+        'enable',
+        'mosaic-lease-broker.service',
+      ]);
+      await runChecked(request.deps, 'systemctl', [
+        '--user',
+        'start',
+        'mosaic-lease-broker.service',
+      ]);
+    }
     if (request.command === 'start' && plan.holder === 'missing') {
       await runChecked(request.deps, 'systemctl', [
         '--user',
@@ -562,6 +631,12 @@ async function applyDesiredLifecycle(
     (agent: FleetRosterV2Agent): boolean =>
       agent.lifecycle.enabled && agent.lifecycle.desiredState === 'running',
   );
+  // Broker before any running agent, same ordering and reason as the
+  // command-driven path above (#1292).
+  if (needsRunningAgent) {
+    await runChecked(deps, 'systemctl', ['--user', 'enable', 'mosaic-lease-broker.service']);
+    await runChecked(deps, 'systemctl', ['--user', 'start', 'mosaic-lease-broker.service']);
+  }
   if (needsRunningAgent && plan.holder === 'missing') {
     await runChecked(deps, 'systemctl', ['--user', 'start', 'mosaic-tmux-holder.service']);
   }