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

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

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

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

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

packages/macp/src/cli.spec.ts

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

packages/macp/src/cli.ts

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

packages/macp/src/errors.ts

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

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

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

packages/macp/src/gate-runner.ts

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

packages/macp/src/index.ts

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

packages/macp/src/types.ts

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

packages/mosaic/framework/tools/git/README.md

@@ -30,7 +30,7 @@ The Gitea API token is **never passed on a curl command line.** An `Authorizatio
 
 ### `--login` override
 
-Both `pr-review.sh` and `issue-comment.sh` accept an optional `--login <name>` flag that overrides the automatically detected Gitea login for that single invocation (as of #1280, `pr-create.sh`, `pr-merge.sh` and `issue-create.sh` accept it too, and it wins over `MOSAIC_GIT_IDENTITY` everywhere). The override selects **which credential the REST write, the `/user` identity lookup, and the read-back all use** — its token is resolved from the tea config for that login name (`get_gitea_token_for_login`), falling back to the repo host's credential when no login is named. The resolved login is **host- and port-bound**: the login's configured URL host **and effective port** (the scheme's default port — 80 for `http`, 443 for `https` — applies when a port is omitted, symmetrically on both sides) must match the repo remote's, so a login name shared across hosts (or an override configured for a different Gitea, including one on a different port of the same host) can never send one host's credential to another — a host or port mismatch fails closed rather than leaking a cross-host token. Resolving the acting identity and the read-back from the _same_ login that performs the write is essential: a write performed under an overridden login must be verified against that login's identity, not the host default's. Callers who need a different login than the host default should pass `--login <reviewer-login>`.
+Both `pr-review.sh` and `issue-comment.sh` accept an optional `--login <name>` flag that overrides the automatically detected Gitea login for that single invocation. The override selects **which credential the REST write, the `/user` identity lookup, and the read-back all use** — its token is resolved from the tea config for that login name (`get_gitea_token_for_login`), falling back to the repo host's credential when no login is named. The resolved login is **host- and port-bound**: the login's configured URL host **and effective port** (the scheme's default port — 80 for `http`, 443 for `https` — applies when a port is omitted, symmetrically on both sides) must match the repo remote's, so a login name shared across hosts (or an override configured for a different Gitea, including one on a different port of the same host) can never send one host's credential to another — a host or port mismatch fails closed rather than leaking a cross-host token. Resolving the acting identity and the read-back from the _same_ login that performs the write is essential: a write performed under an overridden login must be verified against that login's identity, not the host default's. Callers who need a different login than the host default should pass `--login <reviewer-login>`.
 
 As a durable successor to this mechanism, consider giving each reviewer/approver slot its own dedicated Gitea login credential, so that author≠reviewer holds at the credential level rather than relying on wrapper-level `--login` bookkeeping. This is a recommendation for future hardening, not something implemented by this flag.
 
@@ -58,36 +58,6 @@ token file present, both tools fall through to the existing shared-account path
 unchanged, so this feature is a no-op on any host that hasn't provisioned per-slot
 tokens.
 
-### Identity-first principal resolution in the wrappers (#1280)
-
-`resolve_gitea_principal()` (detect-platform.sh) gives the write wrappers —
-`pr-create.sh`, `pr-merge.sh`, `pr-review.sh`, `issue-create.sh`, `issue-comment.sh` —
-ONE precedence for choosing the acting principal:
-
-1. an explicit `--login <name>` (now accepted by all five; operator intent beats
-   environment), then
-2. the per-agent identity above (`MOSAIC_GIT_IDENTITY` env / worktree
-   `mosaic.gitIdentity`) when a per-slot token exists — the wrapper then writes via the
-   REST API with that identity's token and never consults `tea`, so the tea login list
-   cannot shadow the requested principal, then
-3. the tea login list — the LAST resort, never the first, because it enumerates
-   whatever logins the host happens to hold and knows nothing about which seat is
-   calling.
-
-A requested identity whose per-slot token is absent, or a `--login` whose token cannot
-resolve host-bound, **fails loud** (nonzero, naming the identity/login and the expected
-slot) instead of silently writing under whatever account `tea` has configured — that
-silent fallthrough is defect #1280 (reviews, comments, merges, PRs and issues filed
-under the wrong account). `pr-merge.sh --dry-run` reports the principal the merge would
-act as, resolved exactly as the real merge resolves it. ⚠ A **workstation-global**
-`mosaic.gitIdentity` shadows every seat on that host (a fresh clone with no local value
-resolves the global one) — set it per-worktree, not with `--global`.
-
-The resolver is covered by `test-gitea-principal-resolution.sh`; the happy-path
-ordering (identity arm REACHED, not sitting behind a tea failure) by
-`test-pr-create-identity-first.sh`; merge credential binding by
-`test-pr-merge-principal-resolution.sh`.
-
 ### Enabling it for a clone
 
 The framework installer syncs `git-credential-mosaic` to

packages/mosaic/framework/tools/git/detect-platform.sh

@@ -497,32 +497,6 @@ get_gitea_url_for_host() {
     return 1
 }
 
-# Map a Gitea host to the per-agent identity-token slot PREFIX ("gitea-usc" /
-# "gitea-mosaicstack") used by identity-first principal resolution
-# (MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity; #1280). Returns 1 for
-# hosts with no per-slot scheme — callers treat that as "identity does not
-# bind here" and fall through to existing behavior, never as an error. This is
-# the single source of truth for the slot layout: get_gitea_token and
-# resolve_gitea_principal both derive their slot paths from here, so the two
-# resolutions can never disagree about where an identity's credential lives.
-gitea_identity_slot_prefix() {
-    case "$1" in
-        git.uscllc.com)      echo "gitea-usc" ;;
-        git.mosaicstack.dev) echo "gitea-mosaicstack" ;;
-        *) return 1 ;;
-    esac
-}
-
-# Resolve the per-slot token FILE PATH for an identity on a host. Prints the
-# absolute path on success; returns 1 (no output) when the host has no per-slot
-# scheme. Prints a PATH only — never a token value.
-gitea_identity_token_slot() {
-    local identity="$1" host="$2" prefix
-    [[ -n "$identity" ]] || return 1
-    prefix=$(gitea_identity_slot_prefix "$host") || return 1
-    printf '%s\n' "$HOME/.config/mosaic/secrets/gitea-tokens/${prefix}-${identity}.token"
-}
-
 # Resolve a Gitea API token for the given host.
 # Priority: Mosaic credential loader → GITEA_TOKEN env → ~/.git-credentials
 get_gitea_token() {
@@ -543,8 +517,13 @@ get_gitea_token() {
         _ident_src="git config mosaic.gitIdentity"
     fi
     if [[ -n "$_ident" ]]; then
-        local _idtok=""
+        local _idpfx=""
-        if _idtok="$(gitea_identity_token_slot "$_ident" "$host" 2>/dev/null)"; then
+        case "$host" in
+            git.uscllc.com)      _idpfx=gitea-usc ;;
+            git.mosaicstack.dev) _idpfx=gitea-mosaicstack ;;
+        esac
+        if [[ -n "$_idpfx" ]]; then
+            local _idtok="$HOME/.config/mosaic/secrets/gitea-tokens/${_idpfx}-${_ident}.token"
             if [[ -r "$_idtok" ]]; then
                 cat "$_idtok"
                 return 0
@@ -1486,81 +1465,6 @@ raise SystemExit(1)
 PY
 }
 
-# resolve_gitea_principal — identity-first acting-principal resolution shared by
-# the git wrappers (#1280). The defect this fixes: wrappers resolved their
-# acting principal from tea's login list FIRST, and that list enumerates
-# whatever logins happen to be configured on the host — it knows nothing about
-# which seat is calling — so a wrapper invoked with MOSAIC_GIT_IDENTITY=fargo
-# still wrote under whichever account tea held (mos-dt-0), and the correct
-# identity-aware code sat behind arms that only ran when the tea path failed.
-# Precedence here is the contract:
-#   1. an explicit login override ($1, the wrapper's --login) — operator intent
-#      beats environment;
-#   2. MOSAIC_GIT_IDENTITY env, else per-worktree `git config mosaic.gitIdentity`
-#      (mirroring get_gitea_token exactly, so resolver and token resolution can
-#      never disagree) — binds only on hosts with a per-slot token scheme;
-#   3. the tea login list — LAST resort, never the first.
-#
-# Prints exactly one line, three tab-separated fields (machine-readable for
-# wrapper dispatch and tests):
-#   mode        "login" | "identity" | "default"
-#   principal   login name (login) | identity name (identity) | tea login or "" (default)
-#   source      "tea-login:<name>" | "identity-slot:<path>" | "tea-default" | "host-credential"
-#
-# Fails LOUD (nonzero, empty stdout, stderr diagnostic) when an explicit
-# override cannot be honored — a refusal is a good day; silently falling
-# through to whoever tea has configured is the exact defect this resolves:
-#   - login mode: no host-bound token for that tea login. The existence check
-#     runs the same tea-config lookup tea itself uses; the token VALUE is
-#     discarded (never printed, never used).
-#   - identity mode: no per-slot token file for that identity on a recognized
-#     host — the diagnostic names the identity, its source, and the expected
-#     slot path. An identity requested on a host with NO per-slot scheme does
-#     not bind (matching get_gitea_token's containment) and falls to default.
-#
-# NEVER prints a token value — principal names and slot paths only.
-# $1 = explicit login override ("" when absent), $2 = host (default: the
-# origin remote's host).
-resolve_gitea_principal() {
-    local login_override="${1:-}" host="${2:-}" ident ident_src slot login
-    [[ -n "$host" ]] || { host=$(get_remote_host) || return 1; }
-
-    if [[ -n "$login_override" ]]; then
-        get_gitea_token_for_login "$login_override" "$host" >/dev/null || {
-            echo "Error: --login '$login_override' has no host-matched token on host '$host' (tea config lookup); refusing to fall back to any other principal (#1280 identity-first resolution)." >&2
-            return 1
-        }
-        printf 'login\t%s\ttea-login:%s\n' "$login_override" "$login_override"
-        return 0
-    fi
-
-    ident="${MOSAIC_GIT_IDENTITY:-}"
-    ident_src="MOSAIC_GIT_IDENTITY"
-    if [[ -z "$ident" ]]; then
-        ident="$(git config --get mosaic.gitIdentity 2>/dev/null || true)"
-        ident_src="git config mosaic.gitIdentity"
-    fi
-    if [[ -n "$ident" ]] && slot="$(gitea_identity_token_slot "$ident" "$host" 2>/dev/null)"; then
-        if [[ -r "$slot" ]]; then
-            printf 'identity\t%s\tidentity-slot:%s\n' "$ident" "$slot"
-            return 0
-        fi
-        echo "Error: git identity '$ident' requested (via $ident_src) for host '$host', but no per-slot token at $slot (#1280 identity-first resolution)." >&2
-        echo "       Refusing to fall back to the tea login list or shared credentials. Provision the per-slot token, or unset the identity." >&2
-        return 1
-    fi
-
-    # No override requested: tea's login list is the LAST resort. Absence is
-    # not an error here — callers fall back to the host credential, exactly as
-    # they did before this resolver existed (preserved behavior).
-    if login=$(get_gitea_login_for_host "$host" 2>/dev/null); then
-        printf 'default\t%s\ttea-default\n' "$login"
-    else
-        printf 'default\t\thost-credential\n'
-    fi
-    return 0
-}
-
 # Resolve HTTPS basic auth credentials for a Gitea host from ~/.git-credentials.
 # Prints "username:password" for direct curl -u consumption. Callers must not log it.
 get_gitea_basic_auth() {

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -76,36 +76,27 @@ fi
 detect_platform >/dev/null
 
 # Resolve and cache the Gitea REST endpoint + token for the current remote,
-# bound to a SPECIFIC acting principal ($1) selected identity-first (#1280):
+# bound to a SPECIFIC login identity ($1). Populates GITEA_API_ROOT (…/api/v1),
-# an explicit --login wins, else MOSAIC_GIT_IDENTITY / git config
+# GITEA_API_BASE (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
-# mosaic.gitIdentity binds the per-slot credential, else the tea login list
-# (last resort). Populates GITEA_API_ROOT (…/api/v1), GITEA_API_BASE
-# (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
 #
-# The token is resolved for the EFFECTIVE principal so that the single
+# The token is resolved for the EFFECTIVE login (the --login override when
-# credential used for the write ALSO drives the /user identity read and the
+# given, otherwise the detected default) so that the single credential used for
-# read-back — write token and read-back token are the same identity by
+# the write ALSO drives the /user identity read and the read-back — write token
-# construction (this is the credential-ordering fix: a --login override is no
+# and read-back token are the same identity by construction (this is the
-# longer written under one credential and verified under a different default
+# credential-ordering fix: a --login override is no longer written under one
-# one). When $2 is "identity" the principal ($1) is a requested git identity:
+# credential and verified under a different default one). Falls back to the
-# the token MUST resolve from that identity's per-slot token (get_gitea_token's
+# host-scoped credential ONLY when NO --login override was supplied (the
-# identity arm), failing closed rather than borrowing the tea default login —
+# best-effort default path). When $2 is "explicit" the login came from a
-# the tea login list must never shadow a requested identity (#1280). When $2
+# caller-supplied --login: that exact login's token MUST resolve, and we FAIL
-# is "explicit" the principal came from a caller-supplied --login: that exact
+# CLOSED rather than silently downgrading the write to the host default
-# login's token MUST resolve, and we FAIL CLOSED rather than silently
+# identity — otherwise a caller relying on a dedicated per-role credential would
-# downgrading the write to the host default identity. Otherwise the best-effort
+# be told the write succeeded as requested while it was attributed to the shared
-# default path applies (per-login token, else the host-scoped credential).
+# default. Returns non-zero (clear stderr) on any resolution failure.
-# Returns non-zero (clear stderr) on any resolution failure.
 gitea_resolve_api_for_login() {
     local effective_login="$1" override_explicit="${2:-}" host configured_url repo
 
     host=$(get_remote_host)
-    if [[ "$override_explicit" == "identity" ]]; then
+    if [[ -n "$override_explicit" ]]; then
-        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
-            echo "Error: could not resolve the per-slot token for requested git identity '$effective_login' on host '$host'; refusing to fall back to the tea login list or shared credentials (comment write/read-back, #1280)." >&2
-            return 1
-        }
-    elif [[ -n "$override_explicit" ]]; then
         GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
             echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (comment write/read-back)" >&2
             return 1
@@ -327,31 +318,23 @@ if [[ "$PLATFORM" == "github" ]]; then
     gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    # Resolve the acting principal identity-first (#1280): an explicit --login
+    # Resolve the login this comment should be attributed to: the --login
-    # wins; otherwise MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
+    # override when given, otherwise the detected default for this repo's host.
-    # selects the principal when a per-slot token exists (fail-loud when it
+    # A --login override always wins. Otherwise name this repo host's login only
-    # does not); the tea login list is the LAST resort — it knows nothing about
+    # as a best effort: the login name merely selects a per-login token, and
-    # which seat is calling, so resolving from it first wrote under whichever
+    # gitea_resolve_api_for_login falls back to the host credential
-    # account tea had configured (the #1280 family).
+    # (get_gitea_token) when no tea login is named, so the default credential
-    principal_host=$(get_remote_host)
+    # still resolves even when the host tea has no matching login entry.
-    if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$principal_host")"; then
+    EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
-        # resolve_gitea_principal already printed the fail-loud diagnostic.
+    [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login 2>/dev/null || true)
-        exit 1
-    fi
-    PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-    PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
 
-    # Bind the REST endpoint + token to the resolved principal, then derive the
+    # Bind the REST endpoint + token to the effective login, then derive the
     # acting identity from that SAME credential (GET /user). The write below and
     # its read-back both use this credential, so the write is verified against
-    # the identity that actually performed it.
+    # the identity that actually performed it. Passing "explicit" when --login
-    if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+    # was supplied forbids the host-default fallback: an unresolvable explicit
-        gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+    # override fails closed instead of writing under the default identity.
-    elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+    gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
-        gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
-    else
-        gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
-    fi
     ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
 
     comment_id=$(gitea_create_comment_verified "$ISSUE_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {

packages/mosaic/framework/tools/git/issue-create.sh

@@ -1,15 +1,6 @@
 #!/bin/bash
 # issue-create.sh - Create issues on Gitea or GitHub
-# Usage: issue-create.sh -t "Title" [-b "Body"] [-l "label1,label2"] [-m "milestone"] [--login <name>]
+# Usage: issue-create.sh -t "Title" [-b "Body"] [-l "label1,label2"] [-m "milestone"]
-#
-# Acting principal is resolved identity-first (#1280): an explicit --login
-# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
-# mosaic.gitIdentity selects the principal when a per-slot token exists (and
-# the wrapper then creates the issue through the REST API with that identity's
-# token — tea is never invoked, so the tea login list cannot shadow the
-# requested principal); the tea login list is the LAST resort. A requested
-# identity with no per-slot token fails LOUD rather than writing under
-# whichever account tea happens to hold.
 
 set -e
 
@@ -25,14 +16,6 @@ INTERACTIVE=false
 
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
 
-# Acting-principal mode set in the Gitea branch below (from
-# resolve_gitea_principal): "login" when --login was given, "identity" when a
-# git identity bound, "default" otherwise. PRINCIPAL_MODE=login makes the API
-# arm resolve the --login principal's token too, so an explicit --login keeps
-# winning even on the tea-FAILURE fallback arm.
-PRINCIPAL_MODE=""
-PRINCIPAL_NAME=""
-
 gitea_issue_create_api() {
     local host repo token url payload
     host=$(get_remote_host) || {
@@ -43,19 +26,10 @@ gitea_issue_create_api() {
         echo "Error: could not determine repo owner/name for API fallback" >&2
         return 1
     }
-    if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+    token=$(get_gitea_token "$host") || {
-        token=$(get_gitea_token_for_login "$PRINCIPAL_NAME" "$host") || {
+        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-            echo "Error: could not resolve a host-matched Gitea token for --login '$PRINCIPAL_NAME' on host '$host' (API path)" >&2
+        return 1
-            return 1
+    }
-        }
-    else
-        # Identity-first when MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
-        # is set (per-slot token, fail-loud on absence); shared default otherwise.
-        token=$(get_gitea_token "$host") || {
-            echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-            return 1
-        }
-    fi
 
     if [[ -n "$LABELS" || -n "$MILESTONE" ]]; then
         echo "Warning: API fallback currently applies title/body only; labels/milestone require authenticated tea setup." >&2
@@ -93,7 +67,6 @@ Options:
     -b, --body BODY         Issue body/description
     -l, --labels LABELS     Comma-separated labels (e.g., "bug,feature")
     -m, --milestone NAME    Milestone name to assign
-        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
     -i, --interactive       Prompt for missing issue fields
     -h, --help              Show this help message
 
@@ -124,10 +97,6 @@ while [[ $# -gt 0 ]]; do
             MILESTONE="$2"
             shift 2
             ;;
-        --login)
-            LOGIN_OVERRIDE="$2"
-            shift 2
-            ;;
         -i|--interactive)
             INTERACTIVE=true
             shift
@@ -165,37 +134,13 @@ case "$PLATFORM" in
         "${CMD[@]}"
         ;;
     gitea)
-        # Resolve the acting principal identity-first (#1280). The tea login
-        # list is the LAST resort: it knows nothing about which seat is calling,
-        # and a login resolved from it first is what attributed issues to the
-        # wrong account even when MOSAIC_GIT_IDENTITY was set.
-        principal_host=$(get_remote_host 2>/dev/null || true)
-        if ! principal_resolved="$(resolve_gitea_principal "${LOGIN_OVERRIDE:-}" "$principal_host")"; then
-            # resolve_gitea_principal already printed the fail-loud diagnostic.
-            exit 1
-        fi
-        PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-        PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
-
-        if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-            # HAPPY PATH for a requested identity: create through the REST API
-            # with the per-slot token and never invoke tea — the identity arm
-            # must be REACHED, not sit behind a tea failure (#1280).
-            gitea_issue_create_api
-            exit $?
-        fi
-
         if command -v tea >/dev/null 2>&1; then
             REPO_SLUG=$(get_repo_slug)
-            if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+            GITEA_LOGIN_NAME=$(get_gitea_login) || {
-                GITEA_LOGIN_NAME="$PRINCIPAL_NAME"
+                echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
-            else
+                gitea_issue_create_api
-                GITEA_LOGIN_NAME=$(get_gitea_login) || {
+                exit $?
-                    echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
+            }
-                    gitea_issue_create_api
-                    exit $?
-                }
-            fi
             if ! get_gitea_authenticated_user "$GITEA_LOGIN_NAME" >/dev/null; then
                 echo "Warning: Tea authenticated-user validation failed (possible stale user/login); trying Gitea API fallback..." >&2
                 gitea_issue_create_api

packages/mosaic/framework/tools/git/pr-create.sh

@@ -1,15 +1,6 @@
 #!/bin/bash
 # pr-create.sh - Create pull requests on Gitea or GitHub
-# Usage: pr-create.sh -t "Title" [-b "Body"] [-B base] [-H head] [-l "labels"] [-m "milestone"] [--login <name>]
+# Usage: pr-create.sh -t "Title" [-b "Body"] [-B base] [-H head] [-l "labels"] [-m "milestone"]
-#
-# Acting principal is resolved identity-first (#1280): an explicit --login
-# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
-# mosaic.gitIdentity selects the principal when a per-slot token exists (and
-# the wrapper then creates the PR through the REST API with that identity's
-# token — tea is never invoked, so the tea login list cannot shadow the
-# requested principal); the tea login list is the LAST resort. A requested
-# identity with no per-slot token fails LOUD rather than writing under
-# whichever account tea happens to hold.
 
 set -e
 
@@ -28,15 +19,6 @@ ISSUE=""
 
 # get_remote_host, get_gitea_token, get_repo_info, and get_gitea_repo_args are provided by detect-platform.sh
 
-# Acting-principal mode set in the Gitea branch below (from
-# resolve_gitea_principal): "login" when --login was given, "identity" when a
-# git identity bound, "default" otherwise. PRINCIPAL_MODE=login makes the API
-# arm resolve the --login principal's token too, so an explicit --login keeps
-# winning even on the tea-FAILURE fallback arm (otherwise the fallback would
-# silently re-resolve to the environment identity or shared credential).
-PRINCIPAL_MODE=""
-PRINCIPAL_NAME=""
-
 gitea_pr_create_api() {
     local host repo token url payload
     host=$(get_remote_host) || {
@@ -47,19 +29,10 @@ gitea_pr_create_api() {
         echo "Error: could not determine repo owner/name for API fallback" >&2
         return 1
     }
-    if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+    token=$(get_gitea_token "$host") || {
-        token=$(get_gitea_token_for_login "$PRINCIPAL_NAME" "$host") || {
+        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-            echo "Error: could not resolve a host-matched Gitea token for --login '$PRINCIPAL_NAME' on host '$host' (API path)" >&2
+        return 1
-            return 1
+    }
-        }
-    else
-        # Identity-first when MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
-        # is set (per-slot token, fail-loud on absence); shared default otherwise.
-        token=$(get_gitea_token "$host") || {
-            echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-            return 1
-        }
-    fi
 
     if [[ -n "$LABELS" || -n "$MILESTONE" || "$DRAFT" == true ]]; then
         echo "Warning: API fallback applies title/body/head/base only; labels/milestone/draft require authenticated tea setup." >&2
@@ -103,7 +76,6 @@ Options:
     -H, --head BRANCH       Head branch with changes (default: current branch)
     -l, --labels LABELS     Comma-separated labels
     -m, --milestone NAME    Milestone name
-        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
     -i, --issue NUMBER      Link to issue (auto-generates title if not provided)
     -d, --draft             Create as draft PR
     -h, --help              Show this help message
@@ -144,10 +116,6 @@ while [[ $# -gt 0 ]]; do
             MILESTONE="$2"
             shift 2
             ;;
-        --login)
-            LOGIN_OVERRIDE="$2"
-            shift 2
-            ;;
         -i|--issue)
             ISSUE="$2"
             shift 2
@@ -206,41 +174,15 @@ case "$PLATFORM" in
         "${CMD[@]}"
         ;;
     gitea)
-        # Resolve the acting principal identity-first (#1280). The tea login
-        # list is the LAST resort: it knows nothing about which seat is calling,
-        # and a login resolved from it first is what attributed PRs to the wrong
-        # account even when MOSAIC_GIT_IDENTITY was set.
-        principal_host=$(get_remote_host 2>/dev/null || true)
-        if ! principal_resolved="$(resolve_gitea_principal "${LOGIN_OVERRIDE:-}" "$principal_host")"; then
-            # resolve_gitea_principal already printed the fail-loud diagnostic.
-            exit 1
-        fi
-        PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-        PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
-
-        if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
-            # HAPPY PATH for a requested identity: the per-slot token IS the
-            # credential, so create through the REST API directly and never
-            # invoke tea — the identity arm must be REACHED, not sit behind a
-            # tea failure (#1280). Fail-loud on a missing slot already happened
-            # in resolve_gitea_principal.
-            gitea_pr_create_api
-            exit $?
-        fi
-
         # tea pull create syntax. Always pass --repo because tea repo inference
         # is unreliable in Mosaic worktrees/profile shells. Use arrays instead
         # of eval so markdown backticks/body content are not shell-executed.
         REPO_SLUG=$(get_repo_slug)
-        if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+        GITEA_LOGIN_NAME=$(get_gitea_login) || {
-            GITEA_LOGIN_NAME="$PRINCIPAL_NAME"
+            echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
-        else
+            gitea_pr_create_api
-            GITEA_LOGIN_NAME=$(get_gitea_login) || {
+            exit $?
-                echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
+        }
-                gitea_pr_create_api
-                exit $?
-            }
-        fi
         if ! get_gitea_authenticated_user "$GITEA_LOGIN_NAME" >/dev/null; then
             echo "Warning: Tea authenticated-user validation failed (possible stale user/login); trying Gitea API fallback..." >&2
             gitea_pr_create_api

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -1,13 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL] [--login <name>]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
-#
-# Acting principal is resolved identity-first (#1280): an explicit --login
-# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
-# mosaic.gitIdentity selects the credential (per-slot token, fail-loud when
-# absent); the shared host credential is the last resort. The merge is
-# performed with the resolved credential only — never a cross-principal
-# fallback (an HTTP 401 from the identity-bound token is a hard stop).
 
 set -euo pipefail
 
@@ -23,7 +16,6 @@ DRY_RUN=false
 EXPECT_HEAD=""
 CO_AUTHOR_TRAILERS=false
 ESCALATE_TO=""
-LOGIN_OVERRIDE=""
 
 usage() {
     cat <<EOF
@@ -39,7 +31,6 @@ Options:
         --expect-head SHA   Refuse unless the PR head matches this full commit SHA
         --co-author-trailers Build verified trailers from linked PR commit authors
         --escalate-to NAME  Named principal for an unresolved-author BLOCK
-        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
     -h, --help              Show this help message
 
 Examples:
@@ -48,7 +39,6 @@ Examples:
     $(basename "$0") -n 42 -d                 # Squash merge and delete branch
     $(basename "$0") -n 42 --expect-head 0123456789abcdef0123456789abcdef01234567
     $(basename "$0") -n 42 --co-author-trailers --escalate-to tl-mosaic
-    $(basename "$0") -n 42 --login fred-ms    # Merge under the fred-ms tea login
 EOF
     exit "${1:-1}"
 }
@@ -92,14 +82,6 @@ while [[ $# -gt 0 ]]; do
             ESCALATE_TO="$2"
             shift 2
             ;;
-        --login|-l)
-            if [[ $# -lt 2 ]]; then
-                echo "Error: --login requires one tea login name." >&2
-                exit 1
-            fi
-            LOGIN_OVERRIDE="$2"
-            shift 2
-            ;;
         -h|--help)
             usage 0
             ;;
@@ -590,22 +572,9 @@ PY
 merge_gitea_with_api() {
     local host="$1" token attempt_rc
 
-    # Identity-first principal resolution (#1280): an explicit --login wins
+    if ! token=$(get_gitea_token "$host"); then
-    # over MOSAIC_GIT_IDENTITY (operator intent beats environment); otherwise
+        echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
-    # get_gitea_token resolves the identity's per-slot token when an identity
+        return 1
-    # is requested (fail-loud when absent) and the shared host credential only
-    # when no identity is set. No cross-principal fallback: whatever resolves
-    # here is the ONLY credential the merge is attempted with.
-    if [[ -n "$LOGIN_OVERRIDE" ]]; then
-        if ! token=$(get_gitea_token_for_login "$LOGIN_OVERRIDE" "$host"); then
-            echo "Error: --login '$LOGIN_OVERRIDE' has no host-matched token on host '$host'; refusing to merge under any other principal (#1280 identity-first resolution)." >&2
-            return 1
-        fi
-    else
-        if ! token=$(get_gitea_token "$host"); then
-            echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
-            return 1
-        fi
     fi
     if [[ -z "$token" ]]; then
         echo "Error: Required Gitea token resolved empty; refusing merge without changing principals." >&2
@@ -633,25 +602,10 @@ if [[ "$DRY_RUN" == true ]]; then
             echo "Error: Cannot determine host from origin remote URL" >&2
             exit 1
         }
-        # Report the acting principal the merge WOULD use, resolved the same
-        # way the real merge resolves it (#1280) — a dry run that names a
-        # different principal than the merge would act as is a lie.
-        if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$HOST")"; then
-            # Fail-loud diagnostic already printed (unresolvable --login or a
-            # requested identity with no per-slot token).
-            exit 1
-        fi
-        DRY_PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-        DRY_PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
-        case "$DRY_PRINCIPAL_MODE" in
-            login)    DRY_PRINCIPAL_DESC="tea login '$DRY_PRINCIPAL_NAME'" ;;
-            identity) DRY_PRINCIPAL_DESC="git identity '$DRY_PRINCIPAL_NAME' (per-slot credential)" ;;
-            *)        DRY_PRINCIPAL_DESC="default host credential" ;;
-        esac
         if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST as $DRY_PRINCIPAL_DESC with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
         else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST as $DRY_PRINCIPAL_DESC with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
         fi
     else
         echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."

packages/mosaic/framework/tools/git/pr-review.sh

@@ -76,7 +76,7 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -a, --action   Review action: approve, request-changes, comment (required)"
             echo "  -c, --comment  Review comment (required for request-changes)"
-            echo "  -l, --login    Override the detected Gitea tea login (all actions; wins over MOSAIC_GIT_IDENTITY)"
+            echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
             echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
             echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
             echo "  -h, --help     Show this help"
@@ -346,14 +346,7 @@ gitea_resolve_api_for_login() {
     else
         host=$(get_remote_host)
     fi
-    if [[ "$override_explicit" == "identity" ]]; then
+    if [[ -n "$override_explicit" ]]; then
-        # Requested git identity (#1280): the per-slot token MUST resolve via
-        # get_gitea_token's identity arm; never borrow the tea default login.
-        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
-            echo "Error: could not resolve the per-slot token for requested git identity '$effective_login' on host '$host'; refusing to fall back to the tea login list or shared credentials (review write/read-back, #1280)." >&2
-            return 1
-        }
-    elif [[ -n "$override_explicit" ]]; then
         GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
             echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (review write/read-back)" >&2
             return 1
@@ -683,32 +676,29 @@ if [[ "$PLATFORM" == "github" ]]; then
             ;;
     esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    # Resolve the acting principal ONCE for every action, identity-first
-    # (#1280): an explicit --login wins; otherwise MOSAIC_GIT_IDENTITY /
-    # per-worktree git config mosaic.gitIdentity selects the principal when a
-    # per-slot token exists (fail-loud when it does not); the tea login list is
-    # the LAST resort — it enumerates whatever logins this host happens to hold
-    # and knows nothing about which seat is calling, so resolving from it first
-    # wrote under whichever account tea had configured (the #1280 family).
-    principal_host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-    if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$principal_host")"; then
-        # resolve_gitea_principal already printed the fail-loud diagnostic.
-        exit 1
-    fi
-    PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
-    PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
     case $ACTION in
         approve)
-            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
+            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
-            # PRINCIPAL_NAME were resolved once above from --login >
+            # below re-derives the real host from HOST_OVERRIDE/remote independently and
-            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
+            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
-            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+            # under `set -e`, with no origin and no -H, previously killed the script
-            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+            # that support running with no usable origin at all).
-            else
+            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+            # A --login override always wins. Otherwise name this host's login
-            fi
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            # Bind the REST endpoint + token to the effective login, then derive
+            # the acting identity from that SAME credential so the review submit
+            # and its read-back verify against the identity that performed them.
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
             # The review body (if any) travels with the review itself in the REST
@@ -725,16 +715,24 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 echo "Error: Comment required for request-changes"
                 exit 1
             fi
-            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
+            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
-            # PRINCIPAL_NAME were resolved once above from --login >
+            # below re-derives the real host from HOST_OVERRIDE/remote independently and
-            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
+            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
-            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+            # under `set -e`, with no origin and no -H, previously killed the script
-            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+            # that support running with no usable origin at all).
-            else
+            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+            # A --login override always wins. Otherwise name this host's login
-            fi
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
             review_id=$(gitea_submit_review_verified "$PR_NUMBER" "REQUEST_CHANGES" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
@@ -748,16 +746,24 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
+            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
-            # PRINCIPAL_NAME were resolved once above from --login >
+            # below re-derives the real host from HOST_OVERRIDE/remote independently and
-            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
+            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
-            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+            # under `set -e`, with no origin and no -H, previously killed the script
-            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+            # that support running with no usable origin at all).
-            else
+            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+            # A --login override always wins. Otherwise name this host's login
-            fi
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             comment_id=$(gitea_create_comment_verified "$PR_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {
                 echo "Error: could not create and verify a comment on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2

packages/mosaic/framework/tools/git/test-gitea-principal-resolution.sh

@@ -1,255 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for detect-platform.sh's resolve_gitea_principal() — the
-# identity-first acting-principal resolution shared by the git wrappers
-# (mosaicstack/stack #1280).
-#
-# The contract under test (precedence: --login > MOSAIC_GIT_IDENTITY /
-# git config mosaic.gitIdentity > tea login list, which is the LAST resort):
-#   1. identity env + per-slot token present -> mode=identity, principal=
-#      identity name, source names the identity's slot PATH (never a token
-#      value).
-#   2. identity env + per-slot token ABSENT -> FAIL LOUD: nonzero, empty
-#      stdout, stderr naming the identity and the expected slot path.
-#   3. identity env + --login -> --login wins (login mode resolves even when
-#      the identity has no slot — operator intent beats environment).
-#   4. identity unset + no --login -> default mode: the tea login list
-#      resolves the principal exactly as before (preserved behavior).
-#   5. no identity + no host-matching tea login -> default/host-credential
-#      (preserved behavior; absence is not an error on the default path).
-#   6. identity on an UNRECOGNIZED host (no per-slot scheme) -> does not bind;
-#      default mode (containment, mirroring get_gitea_token).
-#   7. --login with no host-bound token for that login -> FAIL LOUD, stderr
-#      naming the login and the host.
-#   8. git config mosaic.gitIdentity is honored when the env var is unset.
-#   9. The resolver NEVER emits a token value — stdout/stderr of every
-#      successful resolution must not contain the slot file's contents.
-#
-# Uses a stubbed tea binary, stubbed tea config.yml, stubbed credentials.json
-# and stubbed per-slot token files under a fake HOME. NEVER reads real secrets.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/gitea-principal-resolution}"
-FAKE_HOME="$WORK_DIR/home"
-REPO_DIR="$WORK_DIR/repo"
-BIN_DIR="$WORK_DIR/bin"
-CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" "$REPO_DIR" "$BIN_DIR"
-
-git -C "$REPO_DIR" init -q
-git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
-
-cat > "$CREDENTIALS_FILE" <<'JSON'
-{
-  "gitea": {
-    "mosaicstack": {
-      "url": "https://git.mosaicstack.dev",
-      "token": "shared-mosaicstack-token"
-    },
-    "usc": {
-      "url": "https://git.uscllc.com",
-      "token": "shared-usc-token"
-    }
-  }
-}
-JSON
-
-# tea's own config store: the source get_gitea_token_for_login reads. Logins
-# "alice" (mosaicstack) and "bob-usc" (usc) carry sentinel token values that
-# the assertions prove are NEVER emitted by the resolver.
-cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
-logins:
-- name: alice
-  url: https://git.mosaicstack.dev
-  token: SECRET-alice-tea-token
-- name: bob-usc
-  url: https://git.uscllc.com
-  token: SECRET-bob-usc-tea-token
-YAML
-
-# Stubbed tea: only what login resolution needs (`login list --output json`).
-cat > "$BIN_DIR/tea" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-if [[ "$*" == "login list --output json" ]]; then
-    cat <<'JSON'
-[
-  {"name":"alice","url":"https://git.mosaicstack.dev","default":true},
-  {"name":"bob-usc","url":"https://git.uscllc.com"}
-]
-JSON
-    exit 0
-fi
-exit 0
-SH
-chmod +x "$BIN_DIR/tea"
-
-# Per-slot identity token with a sentinel value the assertions prove is never
-# emitted (proving "token came from the identity's slot BY PATH, not by value").
-echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
-
-fail=0
-assert_eq() {
-  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"
-  if [[ "$haystack" != *"$needle"* ]]; then
-    echo "FAIL: $desc — missing '$needle' in: $haystack" >&2
-    fail=1
-  fi
-}
-assert_not_contains() {
-  local desc="$1" haystack="$2" needle="$3"
-  if [[ "$haystack" == *"$needle"* ]]; then
-    echo "FAIL: $desc — must not contain '$needle', got: $haystack" >&2
-    fail=1
-  fi
-}
-
-# Runs resolve_gitea_principal for $1=login_override $2=host inside REPO_DIR
-# (per-worktree git config resolves there) under a fake HOME, stubbed tea, and
-# stubbed credentials. Extra env (e.g. MOSAIC_GIT_IDENTITY) via $@.
-call_resolver() {
-  local login="$1" host="$2"; shift 2
-  (
-    cd "$REPO_DIR"
-    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-      DETECT_PLATFORM_SH="$SCRIPT_DIR/detect-platform.sh" "$@" \
-      bash -c 'source "$DETECT_PLATFORM_SH"; resolve_gitea_principal "$1" "$2"' _ "$login" "$host"
-  )
-}
-
-field() { printf '%s' "$1" | cut -f"$2"; }
-
-# ---------------------------------------------------------------------------
-# 1. Identity env + slot present -> identity mode, slot named BY PATH, and no
-#    token value ever emitted.
-# ---------------------------------------------------------------------------
-git -C "$REPO_DIR" config --unset mosaic.gitIdentity 2>/dev/null || true
-out=$(call_resolver "" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "identity mode"            "identity" "$(field "$out" 1)"
-assert_eq "identity principal"       "agentX"   "$(field "$out" 2)"
-assert_eq "identity slot source" \
-  "identity-slot:$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token" \
-  "$(field "$out" 3)"
-assert_not_contains "identity stdout leaks token" "$out" "SECRET"
-
-# ---------------------------------------------------------------------------
-# 2. Identity env + slot ABSENT -> fail loud: nonzero, empty stdout, stderr
-#    naming the identity and the expected slot path.
-# ---------------------------------------------------------------------------
-stderr_file="$WORK_DIR/stderr.tmp"
-set +e
-out=$(call_resolver "" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: missing slot — expected nonzero return, got 0 (stdout='$out')" >&2
-  fail=1
-fi
-if [[ -n "$out" ]]; then
-  echo "FAIL: missing slot — expected empty stdout, got '$out'" >&2
-  fail=1
-fi
-err=$(cat "$stderr_file")
-assert_contains "missing slot names identity"  "$err" "agentNoSlot"
-assert_contains "missing slot names slot path" "$err" \
-  "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"
-assert_not_contains "missing-slot stderr leaks token" "$err" "SECRET"
-
-# ---------------------------------------------------------------------------
-# 3. Identity + --login -> --login wins. Also wins when the identity has NO
-#    slot (no identity check may veto an explicit login).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "alice" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "login beats identity (mode)"      "login" "$(field "$out" 1)"
-assert_eq "login beats identity (principal)" "alice" "$(field "$out" 2)"
-assert_eq "login source" "tea-login:alice" "$(field "$out" 3)"
-out=$(call_resolver "alice" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentNoSlot)
-assert_eq "login beats slot-less identity" "login" "$(field "$out" 1)"
-
-# ---------------------------------------------------------------------------
-# 4. No identity, no --login -> default mode via the tea login list
-#    (preserved behavior).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "" "git.mosaicstack.dev")
-assert_eq "default mode"          "default" "$(field "$out" 1)"
-assert_eq "default principal"     "alice"   "$(field "$out" 2)"
-assert_eq "default source"        "tea-default" "$(field "$out" 3)"
-
-# ---------------------------------------------------------------------------
-# 5. No identity, no --login, no host-matching tea login -> default with the
-#    host credential (absence is not an error on the default path).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "" "git.unknown.test")
-assert_eq "no-match default mode"  "default" "$(field "$out" 1)"
-assert_eq "no-match default principal" "" "$(field "$out" 2)"
-assert_eq "no-match default source" "host-credential" "$(field "$out" 3)"
-
-# ---------------------------------------------------------------------------
-# 6. Identity on an UNRECOGNIZED host -> does not bind; default mode
-#    (containment, mirroring get_gitea_token's scope).
-# ---------------------------------------------------------------------------
-out=$(call_resolver "" "github.com" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "unrecognized host falls to default" "default" "$(field "$out" 1)"
-
-# ---------------------------------------------------------------------------
-# 7. --login with no host-bound token for that login -> fail loud, stderr
-#    naming the login and the host.
-# ---------------------------------------------------------------------------
-: > "$stderr_file"
-set +e
-out=$(call_resolver "ghost-login" "git.mosaicstack.dev" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: unknown --login — expected nonzero return, got 0 (stdout='$out')" >&2
-  fail=1
-fi
-err=$(cat "$stderr_file")
-assert_contains "unknown login names login" "$err" "ghost-login"
-assert_contains "unknown login names host"  "$err" "git.mosaicstack.dev"
-# A cross-host login (exists, but for usc) must ALSO fail loud for mosaicstack.
-set +e
-out=$(call_resolver "bob-usc" "git.mosaicstack.dev" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: cross-host --login — expected nonzero return, got 0" >&2
-  fail=1
-fi
-
-# ---------------------------------------------------------------------------
-# 8. git config mosaic.gitIdentity honored when env is unset.
-# ---------------------------------------------------------------------------
-git -C "$REPO_DIR" config mosaic.gitIdentity agentX
-out=$(call_resolver "" "git.mosaicstack.dev")
-assert_eq "git-config identity mode" "identity" "$(field "$out" 1)"
-assert_eq "git-config identity principal" "agentX" "$(field "$out" 2)"
-git -C "$REPO_DIR" config --unset mosaic.gitIdentity
-
-# ---------------------------------------------------------------------------
-# 9. Cross-host slot layout: the usc slot path is chosen for the usc host.
-# ---------------------------------------------------------------------------
-echo -n "SECRET-agentX-usc-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentX.token"
-out=$(call_resolver "" "git.uscllc.com" MOSAIC_GIT_IDENTITY=agentX)
-assert_eq "usc identity mode" "identity" "$(field "$out" 1)"
-assert_eq "usc slot source" \
-  "identity-slot:$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentX.token" \
-  "$(field "$out" 3)"
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "resolve_gitea_principal identity-first resolution regression passed"
-fi
-
-exit "$fail"

packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh

@@ -77,30 +77,12 @@ exit 0
 SH
 chmod +x "$BIN_DIR/tea"
 
-# TRIPWIRE provider stub: this harness tests argv construction, so ANY curl
-# call is a failure of that contract (and, before this stub existed, a LIVE
-# write — the #1282–#1287 incident: the seat's real HOME leaked a global
-# mosaic.gitIdentity, flipping the wrapper into identity mode whose real
-# per-slot token created real issues on the forge). Fail loudly instead.
-cat > "$BIN_DIR/curl" <<'SH'
-#!/usr/bin/env bash
-echo "FAIL: body-safety harness reached a provider request — this test must never curl" >&2
-exit 99
-SH
-chmod +x "$BIN_DIR/curl"
-
-# Hermetic invocation: fake HOME (no credentials, no tea config, no token
-# slots) and GIT_CONFIG_GLOBAL severed — `git config --get mosaic.gitIdentity`
-# otherwise resolves the WORKSTATION's global identity (mos-dt-0 on the seat
-# that wrote this) and reroutes the wrapper into identity mode (#1280 family).
 (
     cd "$REPO_DIR"
-    env -i HOME="$WORK_DIR/home" PATH="$BIN_DIR:$PATH" \
+    PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+    MOSAIC_TEST_RECEIVED="$RECEIVED_FILE" \
-      MOSAIC_TEST_RECEIVED="$RECEIVED_FILE" \
+    "$SCRIPT_DIR/issue-create.sh" -t "Body safety test" -b "$BODY"
-      "$SCRIPT_DIR/issue-create.sh" -t "Body safety test" -b "$BODY"
 ) >/dev/null
-mkdir -p "$WORK_DIR/home"
 
 # 1. No command substitution executed anywhere in the pipeline.
 if [[ -e "$SENTINEL" ]]; then

packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh

@@ -47,31 +47,14 @@ SH
 chmod +x "$BIN_DIR/tea" "$BIN_DIR/curl"
 
 run_wrapper() {
-  # Hermetic: fake HOME (fixture credentials only, no token slots, no tea
-  # config) and GIT_CONFIG_GLOBAL severed — `git config --get
-  # mosaic.gitIdentity` otherwise resolves the WORKSTATION's global identity
-  # and reroutes the wrapper into identity mode before the tea paths this
-  # harness exercises (#1280 family; see test-issue-create-body-safety.sh).
-  # An `env …` prefix (used for MOSAIC_TEA_STALE_USER) is re-wrapped, not
-  # doubled: arguments beginning with "env" are shifted past.
-  local env_pairs=()
-  if [[ "${1:-}" == "env" ]]; then
-    shift
-    while [[ "$#" -gt 0 && "$1" == *=* ]]; do
-      env_pairs+=("$1")
-      shift
-    done
-  fi
   (
     cd "$REPO_DIR"
-    env -i HOME="$WORK_DIR/home" PATH="$BIN_DIR:$PATH" \
+    PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+    MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+    MOSAIC_TEST_LOG="$LOG_FILE" \
-      MOSAIC_TEST_LOG="$LOG_FILE" "${env_pairs[@]}" \
+    "$@"
-      "$@"
   )
 }
-mkdir -p "$WORK_DIR/home"
 
 : > "$LOG_FILE"
 printf 'Interactive title\nInteractive body\nlabel-a,label-b\nM1\n' | run_wrapper "$SCRIPT_DIR/issue-create.sh" -i >/dev/null

packages/mosaic/framework/tools/git/test-pr-create-identity-first.sh

@@ -1,244 +0,0 @@
-#!/usr/bin/env bash
-# Load-bearing regression harness for pr-create.sh identity-first principal
-# resolution (mosaicstack/stack #1280).
-#
-# The failure this harness is written down to catch: `MOSAIC_GIT_IDENTITY=fargo
-# pr-create.sh …` produces a PR attributed to `mos-dt-0` (whichever account the
-# tea login list happens to hold). Before #1280 the identity-aware code existed
-# but sat on the API arm that only ran when the tea path FAILED — tea succeeded,
-# so the identity arm never executed, and every test that did not check ORDERING
-# passed. This harness checks ordering directly:
-#
-#   1. identity set + slot present -> the PR is created via the REST API with
-#      the identity's per-slot token (asserted by sentinel value AT the fake
-#      provider), and tea's `pr create` is NEVER invoked.
-#   2. identity set + slot ABSENT -> nonzero, stderr naming the identity and
-#      the expected slot path; neither tea `pr create` nor any API request
-#      fires. No silent fallback to the tea login list.
-#   3. identity set + --login -> --login wins: tea runs WITH the explicit
-#      --login, no API request.
-#   4. nothing set -> preserved behavior: tea path with the tea-list login.
-#
-# Uses a stubbed tea, a stubbed curl provider, stubbed credentials.json and
-# per-slot token under a fake HOME. NEVER reads real secrets or hits a live
-# forge — all assertions are against the stubs' logs.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-identity-first}"
-FAKE_HOME="$WORK_DIR/home"
-REPO_DIR="$WORK_DIR/repo"
-TOOLS_DIR="$WORK_DIR/tools"
-BIN_DIR="$WORK_DIR/bin"
-LOG_FILE="$WORK_DIR/calls.log"
-CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" \
-  "$REPO_DIR" "$TOOLS_DIR/git" "$TOOLS_DIR/_lib" "$BIN_DIR"
-
-# Fixture: the real scripts under test, copied so sibling stubs (and the
-# ../_lib credential loader) resolve inside the fixture tree.
-cp "$SCRIPT_DIR/pr-create.sh" "$TOOLS_DIR/git/pr-create.sh"
-cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS_DIR/git/detect-platform.sh"
-cp "$SCRIPT_DIR/../_lib/credentials.sh" "$TOOLS_DIR/_lib/credentials.sh"
-chmod +x "$TOOLS_DIR/git/pr-create.sh"
-
-git -C "$REPO_DIR" init -q
-git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
-
-cat > "$CREDENTIALS_FILE" <<'JSON'
-{
-  "gitea": {
-    "mosaicstack": {
-      "url": "https://git.mosaicstack.dev",
-      "token": "shared-mosaicstack-token"
-    }
-  }
-}
-JSON
-
-cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
-logins:
-- name: alice
-  url: https://git.mosaicstack.dev
-  token: SECRET-alice-tea-token
-YAML
-
-echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
-
-: > "$LOG_FILE"
-
-# Stubbed tea: records every invocation; `login list` feeds login resolution;
-# `api --login <n> /user` feeds get_gitea_authenticated_user; `pr create` marks
-# the marker file (its presence fails the identity-mode assertions).
-cat > "$BIN_DIR/tea" <<SH
-#!/usr/bin/env bash
-set -euo pipefail
-printf 'TEA: %s\n' "\$*" >> "$LOG_FILE"
-if [[ "\$*" == "login list --output json" ]]; then
-    cat <<'JSON'
-[
-  {"name":"alice","url":"https://git.mosaicstack.dev","default":true}
-]
-JSON
-    exit 0
-fi
-if [[ "\${1:-}" == "api" ]]; then
-    printf '%s\n' '{"login":"alice"}'
-    exit 0
-fi
-if [[ "\$*" == pr\ create* ]]; then
-    echo "TEA-PR-CREATE-INVOKED" >> "$LOG_FILE"
-    exit 0
-fi
-exit 0
-SH
-chmod +x "$BIN_DIR/tea"
-
-# Stubbed provider: records the URL and the Authorization header VALUE it
-# received, answers 201 with a created-PR object. The sentinel token values are
-# synthetic fixtures — asserting them at the provider proves WHICH slot's
-# credential carried the write.
-cat > "$BIN_DIR/curl" <<SH
-#!/usr/bin/env bash
-set -euo pipefail
-url=""
-auth=""
-while [[ \$# -gt 0 ]]; do
-    case "\$1" in
-        -H)
-            case "\$2" in
-                Authorization*) auth="\$2" ;;
-            esac
-            shift 2
-            ;;
-        *)  [[ -n "\$1" && "\$1" != -* ]] && url="\$1"
-            shift
-            ;;
-    esac
-done
-printf 'CURL-URL: %s\nCURL-AUTH: %s\n' "\$url" "\$auth" >> "$LOG_FILE"
-cat <<'JSON'
-{"number": 1299, "html_url": "https://git.mosaicstack.dev/mosaicstack/stack/pulls/1299"}
-JSON
-exit 0
-SH
-chmod +x "$BIN_DIR/curl"
-
-fail=0
-assert_contains() {
-  local desc="$1" needle="$2"
-  if ! grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log does not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-assert_not_contains() {
-  local desc="$1" needle="$2"
-  if grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log must not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-
-EXTRA_ARGS=""
-run_pr_create() {
-  # "$@" carries ONLY environment assignments (VAR=value); EXTRA_ARGS (if
-  # set) carries wrapper arguments, so `env` never mistakes a wrapper flag
-  # like --login for one of its own.
-  (
-    cd "$REPO_DIR"
-    # shellcheck disable=SC2086 # EXTRA_ARGS is deliberately word-split wrapper args
-    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" "$@" \
-      bash "$TOOLS_DIR/git/pr-create.sh" -t "Test PR" -B next -H fix/test $EXTRA_ARGS
-  )
-}
-
-# ---------------------------------------------------------------------------
-# 1. HAPPY PATH (the load-bearing ordering test): identity set + slot present
-#    -> REST API with the per-slot token; tea `pr create` NEVER invoked.
-# ---------------------------------------------------------------------------
-set +e
-out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentX 2>"$WORK_DIR/stderr-1.tmp")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: identity happy path — expected rc=0, got $rc" >&2
-  cat "$WORK_DIR/stderr-1.tmp" >&2
-  fail=1
-fi
-assert_contains "identity happy path reaches the API" "CURL-URL: https://git.mosaicstack.dev/api/v1/repos/mosaicstack/stack/pulls"
-assert_contains "identity happy path carries the slot token" "CURL-AUTH: Authorization: token SECRET-agentX-slot-token"
-assert_not_contains "identity happy path must NOT invoke tea pr create" "TEA-PR-CREATE-INVOKED"
-
-# ---------------------------------------------------------------------------
-# 2. Identity set + slot ABSENT -> fail loud BEFORE any write: nonzero, stderr
-#    naming identity + slot path, no tea pr create, no API request.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$WORK_DIR/stderr-2.tmp")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: missing slot — expected nonzero return, got 0 (stdout='$out')" >&2
-  fail=1
-fi
-err=$(cat "$WORK_DIR/stderr-2.tmp")
-if [[ "$err" != *"agentNoSlot"* ]]; then
-  echo "FAIL: missing slot — stderr does not name the identity:" >&2
-  echo "$err" >&2
-  fail=1
-fi
-if [[ "$err" != *"$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"* ]]; then
-  echo "FAIL: missing slot — stderr does not name the expected slot path:" >&2
-  echo "$err" >&2
-  fail=1
-fi
-assert_not_contains "missing slot must not reach tea pr create" "TEA-PR-CREATE-INVOKED"
-assert_not_contains "missing slot must not reach the API" "CURL-URL"
-
-# ---------------------------------------------------------------------------
-# 3. Identity set + --login -> --login wins: tea runs WITH the explicit login.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-EXTRA_ARGS="--login alice"
-set +e
-out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentX 2>"$WORK_DIR/stderr-3.tmp")
-rc=$?
-set -e
-EXTRA_ARGS=""
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: login override — expected rc=0, got $rc" >&2
-  cat "$WORK_DIR/stderr-3.tmp" >&2
-  fail=1
-fi
-assert_contains "login override drives tea with the explicit login" "TEA: pr create --repo mosaicstack/stack --login alice"
-assert_not_contains "login override must not hit the API" "CURL-URL"
-
-# ---------------------------------------------------------------------------
-# 4. Nothing set -> preserved behavior: tea path with the tea-list login.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_create 2>"$WORK_DIR/stderr-4.tmp")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: default path — expected rc=0, got $rc" >&2
-  cat "$WORK_DIR/stderr-4.tmp" >&2
-  fail=1
-fi
-assert_contains "default path still uses the tea-list login" "TEA: pr create --repo mosaicstack/stack --login alice"
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "pr-create identity-first happy-path regression passed"
-fi
-
-exit "$fail"

packages/mosaic/framework/tools/git/test-pr-merge-principal-resolution.sh

@@ -1,247 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for pr-merge.sh identity-first principal resolution
-# (mosaicstack/stack #1280).
-#
-# Covers:
-#   1. --dry-run reports the acting principal the merge WOULD use, resolved the
-#      same way the real merge resolves it: --login > MOSAIC_GIT_IDENTITY /
-#      git config mosaic.gitIdentity > shared host credential. (The pre-#1280
-#      deployed copy reported a tea login that the merge would not act as.)
-#   2. --dry-run fails closed when the requested principal has no credential:
-#      unknown --login, or an identity with no per-slot token (stderr names
-#      the login / the identity and its slot path).
-#   3. The real merge POST carries the resolved principal's credential and no
-#      other: --login merges with that login's tea-config token; an identity
-#      merges with the per-slot token; an unresolvable --login never reaches
-#      the provider.
-#
-# Fixture pattern from test-pr-merge-head-pin.sh: the scripts under test are
-# copied into a fixture tree with stubbed pr-metadata.sh / ci-queue-wait.sh
-# siblings; the provider is a stubbed curl that records the credential it
-# received. NEVER reads real secrets or hits a live forge.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-principal-resolution}"
-FAKE_HOME="$WORK_DIR/home"
-REPO_DIR="$WORK_DIR/repo"
-TOOLS_DIR="$WORK_DIR/tools"
-BIN_DIR="$WORK_DIR/bin"
-LOG_FILE="$WORK_DIR/calls.log"
-CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
-SHA=0123456789abcdef0123456789abcdef01234567
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" \
-  "$REPO_DIR" "$TOOLS_DIR/git" "$TOOLS_DIR/_lib" "$BIN_DIR"
-
-cp "$SCRIPT_DIR/pr-merge.sh" "$TOOLS_DIR/git/pr-merge.sh"
-cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS_DIR/git/detect-platform.sh"
-cp "$SCRIPT_DIR/../_lib/credentials.sh" "$TOOLS_DIR/_lib/credentials.sh"
-chmod +x "$TOOLS_DIR/git/pr-merge.sh"
-
-git -C "$REPO_DIR" init -q
-git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
-
-# Stubbed siblings pr-merge.sh resolves relative to its own SCRIPT_DIR.
-cat > "$TOOLS_DIR/git/pr-metadata.sh" <<SH
-#!/usr/bin/env bash
-printf '%s\n' '{"baseRefName":"next","headRefName":"fix/pinned","headRefOid":"$SHA","headRepository":"mosaicstack/stack","title":"Test PR","author":{"login":"contributor"}}'
-SH
-cat > "$TOOLS_DIR/git/ci-queue-wait.sh" <<'SH'
-#!/usr/bin/env bash
-exit 0
-SH
-chmod +x "$TOOLS_DIR/git/pr-metadata.sh" "$TOOLS_DIR/git/ci-queue-wait.sh"
-
-cat > "$CREDENTIALS_FILE" <<'JSON'
-{
-  "gitea": {
-    "mosaicstack": {
-      "url": "https://git.mosaicstack.dev",
-      "token": "shared-mosaicstack-token"
-    }
-  }
-}
-JSON
-
-cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
-logins:
-- name: fred-ms
-  url: https://git.mosaicstack.dev
-  token: SECRET-fred-ms-tea-token
-YAML
-
-echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
-
-: > "$LOG_FILE"
-
-# Stubbed tea for login-list resolution only.
-cat > "$BIN_DIR/tea" <<'SH'
-#!/usr/bin/env bash
-set -euo pipefail
-if [[ "$*" == "login list --output json" ]]; then
-    cat <<'JSON'
-[
-  {"name":"fred-ms","url":"https://git.mosaicstack.dev","default":true}
-]
-JSON
-    exit 0
-fi
-exit 0
-SH
-chmod +x "$BIN_DIR/tea"
-
-# Stubbed provider. pr-merge passes curl config on STDIN with -K -; the stub
-# reads stdin, records the Authorization header it received, answers 200.
-cat > "$BIN_DIR/curl" <<SH
-#!/usr/bin/env bash
-set -euo pipefail
-url=""
-out_file=""
-stdin_config=""
-if [[ ! -t 0 ]]; then
-    stdin_config="\$(cat || true)"
-fi
-while [[ \$# -gt 0 ]]; do
-    case "\$1" in
-        -o) out_file="\$2"; shift 2 ;;
-        -K|-w|--max-filesize|--max-time|--connect-timeout|-sS) shift 2 ;;
-        *)  [[ -n "\$1" && "\$1" != -* && -z "\$url" ]] && url="\$1"
-            shift
-            ;;
-    esac
-done
-auth="\$(printf '%s' "\$stdin_config" | grep -o 'Authorization: token [^"]*' || true)"
-printf 'CURL-URL: %s\nCURL-AUTH: %s\n' "\$url" "\$auth" >> "$LOG_FILE"
-[[ -n "\$out_file" ]] && printf '{}' > "\$out_file"
-printf '200\n'
-exit 0
-SH
-chmod +x "$BIN_DIR/curl"
-
-fail=0
-assert_contains_log() {
-  local desc="$1" needle="$2"
-  if ! grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log does not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-assert_not_contains_log() {
-  local desc="$1" needle="$2"
-  if grep -qF -- "$needle" "$LOG_FILE"; then
-    echo "FAIL: $desc — log must not contain '$needle':" >&2
-    cat "$LOG_FILE" >&2
-    fail=1
-  fi
-}
-
-run_pr_merge() {
-  local extra_args="$1"; shift
-  (
-    cd "$REPO_DIR"
-    # shellcheck disable=SC2086 # extra_args is deliberately word-split wrapper args
-    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
-      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
-      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" "$@" \
-      bash "$TOOLS_DIR/git/pr-merge.sh" -n 42 $extra_args
-  )
-}
-
-# ---------------------------------------------------------------------------
-# 1. --dry-run reports the resolved acting principal truthfully.
-# ---------------------------------------------------------------------------
-out=$(run_pr_merge "--dry-run" MOSAIC_GIT_IDENTITY=agentX)
-if [[ "$out" != *"as git identity 'agentX' (per-slot credential)"* ]]; then
-  echo "FAIL: dry-run identity — principal not reported: $out" >&2
-  fail=1
-fi
-
-out=$(run_pr_merge "--dry-run --login fred-ms" MOSAIC_GIT_IDENTITY=agentX)
-if [[ "$out" != *"as tea login 'fred-ms'"* ]]; then
-  echo "FAIL: dry-run login override — login not reported (must beat env identity): $out" >&2
-  fail=1
-fi
-
-out=$(run_pr_merge "--dry-run")
-if [[ "$out" != *"as default host credential"* ]]; then
-  echo "FAIL: dry-run default — not reported: $out" >&2
-  fail=1
-fi
-
-# ---------------------------------------------------------------------------
-# 2. --dry-run fails closed when the requested principal has no credential.
-# ---------------------------------------------------------------------------
-stderr_file="$WORK_DIR/stderr.tmp"
-set +e
-out=$(run_pr_merge "--dry-run --login ghost" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]] || [[ "$(cat "$stderr_file")" != *"ghost"* ]]; then
-  echo "FAIL: dry-run unknown --login — expected fail-loud naming 'ghost', rc=$rc" >&2
-  cat "$stderr_file" >&2
-  fail=1
-fi
-
-: > "$stderr_file"
-set +e
-out=$(run_pr_merge "--dry-run" MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$stderr_file")
-rc=$?
-set -e
-err=$(cat "$stderr_file")
-if [[ "$rc" -eq 0 ]] || [[ "$err" != *"agentNoSlot"* ]] \
-  || [[ "$err" != *"$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"* ]]; then
-  echo "FAIL: dry-run identity without slot — expected fail-loud naming identity + slot path, rc=$rc" >&2
-  echo "$err" >&2
-  fail=1
-fi
-
-# ---------------------------------------------------------------------------
-# 3. The real merge POST carries the resolved principal's credential ONLY.
-# ---------------------------------------------------------------------------
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_merge "--login fred-ms" MOSAIC_GIT_IDENTITY=agentX 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: merge with --login — expected rc=0, got $rc" >&2
-  cat "$stderr_file" >&2
-  fail=1
-fi
-assert_contains_log "merge --login uses the login token" "CURL-AUTH: Authorization: token SECRET-fred-ms-tea-token"
-assert_not_contains_log "merge --login must not use the identity slot token" "SECRET-agentX-slot-token"
-assert_not_contains_log "merge --login must not use the shared token" "shared-mosaicstack-token"
-
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_merge "" MOSAIC_GIT_IDENTITY=agentX 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -ne 0 ]]; then
-  echo "FAIL: merge with identity — expected rc=0, got $rc" >&2
-  cat "$stderr_file" >&2
-  fail=1
-fi
-assert_contains_log "merge identity uses the per-slot token" "CURL-AUTH: Authorization: token SECRET-agentX-slot-token"
-assert_not_contains_log "merge identity must not use the shared token" "shared-mosaicstack-token"
-
-: > "$LOG_FILE"
-set +e
-out=$(run_pr_merge "--login ghost" 2>"$stderr_file")
-rc=$?
-set -e
-if [[ "$rc" -eq 0 ]]; then
-  echo "FAIL: merge with unknown --login — expected nonzero, got 0" >&2
-  fail=1
-fi
-assert_not_contains_log "merge with unknown --login must not reach the provider" "CURL-URL"
-
-if [[ "$fail" -eq 0 ]]; then
-  echo "pr-merge identity-first principal resolution regression passed"
-fi
-
-exit "$fail"

packages/mosaic/package.json

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