@omega.js/backend 0.1.0

package/test/cli/target.test.js

@@ -0,0 +1,182 @@
+/**
+ * Test: which stack a backend CLI subcommand talks to
+ * ([#51](https://github.com/Omega-JS-Stack/omega/issues/51)).
+ *
+ * Ruling (uniformity amendment, Ian 2026-07-30): EVERY backend CLI subcommand
+ * targets the EMULATOR by default — reads and writes alike, one rule for the
+ * whole surface; `--production` is the only opt-in to touch live. A habitual
+ * `--emulator` names the default and consults nothing.
+ *
+ * Two layers: the resolver itself (pure), then the two command classes actually
+ * asking it — `initFirebase` is swapped for a recorder there because the real one
+ * would reach for a service account and a live project.
+ *
+ * Run: npx omega test backend:cli/target
+ */
+const { resolveTarget } = require('../../dist/cli/utils/target.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const FIREBASE_INIT_PATH = require.resolve('../../dist/cli/commands/firebase-init.js');
+const FIRESTORE_PATH = require.resolve('../../dist/cli/commands/firestore.js');
+const AUTH_PATH = require.resolve('../../dist/cli/commands/auth.js');
+
+// A firebase-admin stand-in: the writes the subcommands make, recorded.
+function recordingAdmin() {
+  const writes = [];
+
+  return {
+    writes,
+    firestore: () => ({
+      doc: (docPath) => ({
+        set: async (data, options) => writes.push({ op: 'set', docPath, data, options }),
+        delete: async () => writes.push({ op: 'delete', docPath }),
+      }),
+    }),
+    auth: () => ({
+      getUser: async (uid) => ({ uid, email: null, toJSON: () => ({ uid }) }),
+      getUserByEmail: async (email) => ({ uid: 'uid-for-email', email, toJSON: () => ({ email }) }),
+      setCustomUserClaims: async (uid, claims) => writes.push({ op: 'set-claims', uid, claims }),
+      deleteUser: async (uid) => writes.push({ op: 'delete-user', uid }),
+    }),
+  };
+}
+
+// Run a CLI subcommand with the Firebase door swapped for a recorder, capturing
+// both the target it asked for and everything it printed.
+async function runSubcommand(commandPath, args, argv) {
+  const originalInit = require.cache[FIREBASE_INIT_PATH];
+  const originalLog = console.log;
+  const admin = recordingAdmin();
+  const asked = [];
+  const printed = [];
+
+  require.cache[FIREBASE_INIT_PATH] = {
+    id: FIREBASE_INIT_PATH,
+    filename: FIREBASE_INIT_PATH,
+    loaded: true,
+    exports: {
+      initFirebase: (options) => {
+        asked.push(options);
+        return { admin, projectId: options.emulator ? 'demo-fixture' : 'live-fixture' };
+      },
+      resolveProjectId: () => 'demo-fixture',
+    },
+  };
+
+  // Drop the command module so it re-requires the stubbed door.
+  delete require.cache[commandPath];
+  const Command = require(commandPath);
+
+  console.log = (...line) => printed.push(line.map(String).join(' '));
+
+  try {
+    const main = {
+      firebaseProjectPath: __dirname,
+      argv: { _: args, ...argv },
+      options: {},
+    };
+
+    await new Command(main).execute();
+  } finally {
+    console.log = originalLog;
+    delete require.cache[commandPath];
+    if (originalInit) {
+      require.cache[FIREBASE_INIT_PATH] = originalInit;
+    } else {
+      delete require.cache[FIREBASE_INIT_PATH];
+    }
+  }
+
+  return { emulator: asked[0]?.emulator, output: printed.join('\n'), writes: admin.writes };
+}
+
+module.exports = defineCases({
+  description: 'CLI target selection — emulator by default, live only with --production',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'every-subcommand-defaults-to-the-emulator',
+      async run({ assert }) {
+        assert.equal(resolveTarget({}).emulator, true, 'no flags should default to the emulator');
+        assert.equal(resolveTarget({}).label, 'emulator', 'no flags should be labelled emulator');
+      },
+    },
+
+    {
+      name: 'production-flag-is-the-only-way-to-the-live-stack',
+      async run({ assert }) {
+        assert.equal(resolveTarget({ production: true }).emulator, false, '--production should hit live');
+        assert.equal(resolveTarget({ production: true }).label, 'production', '--production should be labelled production');
+      },
+    },
+
+    {
+      name: 'emulator-flag-names-the-default-and-consults-nothing',
+      async run({ assert }) {
+        assert.equal(resolveTarget({ emulator: true }).emulator, true, '--emulator lands where the default already goes');
+        assert.equal(resolveTarget({ emulator: true, production: true }).emulator, false, '--production wins; --emulator is not consulted');
+      },
+    },
+
+    {
+      name: 'firestore-set-asks-for-the-emulator-with-no-flag',
+      async run({ assert }) {
+        const run = await runSubcommand(FIRESTORE_PATH, ['firestore:set', 'users/_test-target', '{"a":1}'], {});
+
+        assert.equal(run.emulator, true, 'firestore:set should have initialized against the emulator');
+        assert.equal(run.writes.length, 1, 'The document should have been written');
+        assert.equal(run.output.includes('emulator'), true, `The output should name the stack it hit: ${run.output}`);
+      },
+    },
+
+    {
+      name: 'firestore-set-with-production-asks-for-the-live-stack',
+      async run({ assert }) {
+        const run = await runSubcommand(FIRESTORE_PATH, ['firestore:set', 'users/_test-target', '{"a":1}'], { production: true });
+
+        assert.equal(run.emulator, false, 'firestore:set --production should have initialized against live');
+        assert.equal(run.output.includes('production'), true, `The output should name the stack it hit: ${run.output}`);
+      },
+    },
+
+    {
+      name: 'auth-set-claims-asks-for-the-emulator-with-no-flag',
+      async run({ assert }) {
+        const run = await runSubcommand(AUTH_PATH, ['auth:set-claims', '_test-uid', '{"admin":true}'], {});
+
+        assert.equal(run.emulator, true, 'auth:set-claims should have initialized against the emulator');
+        assert.equal(run.writes.length, 1, 'The claims should have been set');
+        assert.equal(run.output.includes('emulator'), true, `The output should name the stack it hit: ${run.output}`);
+      },
+    },
+
+    {
+      name: 'auth-set-claims-with-production-asks-for-the-live-stack',
+      async run({ assert }) {
+        const run = await runSubcommand(AUTH_PATH, ['auth:set-claims', '_test-uid', '{"admin":true}'], { production: true });
+
+        assert.equal(run.emulator, false, 'auth:set-claims --production should have initialized against live');
+        assert.equal(run.output.includes('production'), true, `The output should name the stack it hit: ${run.output}`);
+      },
+    },
+
+    {
+      name: 'a-read-subcommand-follows-the-same-emulator-default',
+      async run({ assert }) {
+        const run = await runSubcommand(AUTH_PATH, ['auth:get', '_test-uid'], {});
+
+        assert.equal(run.emulator, true, 'auth:get should default to the emulator like everything else');
+      },
+    },
+
+    {
+      name: 'a-read-subcommand-reaches-live-with-production',
+      async run({ assert }) {
+        const run = await runSubcommand(AUTH_PATH, ['auth:get', '_test-uid'], { production: true });
+
+        assert.equal(run.emulator, false, 'auth:get --production should hit live');
+      },
+    },
+  ],
+});

package/test/cli/templates.test.js

@@ -0,0 +1,66 @@
+/**
+ * Test: the shipped scaffold templates
+ * ([#278](https://github.com/Omega-JS-Stack/omega/issues/278),
+ * [#279](https://github.com/Omega-JS-Stack/omega/issues/279)).
+ *
+ * `templates/` is what setup writes into a consumer that carries no file of
+ * its own, so a template's default IS the brand's default until someone edits
+ * it. Two defaults are pinned here: storage denies everything (a brand that
+ * serves files opts in deliberately, per-path), and the internal welcome page
+ * carries its own title instead of 404.html's.
+ *
+ * Pure file reads — no project, no emulator.
+ *
+ * Run: npx omega test backend:cli/templates
+ */
+const fs = require('fs');
+const path = require('path');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
+
+function readTemplate(...segments) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, ...segments), 'utf8');
+}
+
+function readTitle(html) {
+  const match = html.match(/<title>([^<]*)<\/title>/);
+
+  return match ? match[1] : null;
+}
+
+module.exports = defineCases({
+  description: 'Shipped templates: storage denies by default, the welcome page owns its title',
+  type: 'group',
+  timeout: 10000,
+
+  tests: [
+    {
+      name: 'storage-rules-template-denies-by-default',
+      auth: 'none',
+
+      async run({ assert }) {
+        const rules = readTemplate('storage.rules');
+        const allows = rules.split('\n').map((line) => line.trim()).filter((line) => line.startsWith('allow '));
+
+        assert.equal(allows.length, 1, `the template must carry exactly one allow rule (found ${allows.length})`);
+        assert.match(allows[0], /^allow read, write:\s*if false;$/, `the shipped default must deny everything (found "${allows[0]}")`);
+        assert.equal(rules.includes('request.auth'), false, 'the scaffold default must not grant on authentication alone');
+      },
+    },
+
+    {
+      name: 'welcome-page-template-titles-itself',
+      auth: 'none',
+
+      async run({ assert }) {
+        const index = readTemplate('public', 'index.html');
+        const notFound = readTemplate('public', '404.html');
+
+        assert.equal(readTitle(index), 'Welcome', 'index.html must title itself, not carry 404.html\'s title');
+        assert.equal(index.includes('Welcome!'), true, 'index.html is still the internal welcome page');
+        assert.equal(readTitle(notFound), '404 Error Page', '404.html keeps its own title');
+      },
+    },
+  ],
+});

package/test/cli/test-runner-env.test.js

@@ -0,0 +1,115 @@
+/**
+ * Test: the env the test runner child is spawned with
+ * ([#292](https://github.com/Omega-JS-Stack/omega/issues/292)).
+ *
+ * The command carried the two emulator hosts but never the PROJECT they belong
+ * to, so the runner's `process.env.GCLOUD_PROJECT` was empty and every read of
+ * it downstream fell back to a default — including the auth bulk-clear URL,
+ * which the emulator answers 200 for whatever project it names. The wipe
+ * reported success and cleared a store the run never touched.
+ *
+ * Run: npx omega test backend:cli/test-runner-env
+ *
+ * The command builder is pure (a resolved test config in, a shell string out),
+ * so this runs here directly — the wipe's own behavior against a real emulator
+ * is proven in helpers/wipe-auth-project.
+ */
+const TestCommand = require('../../dist/cli/commands/test.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const PROJECT_ID = 'demo-omega-backend';
+
+// A resolved test config the way execute() builds one (loadProjectConfig has
+// already hard-failed on a missing cloud.config.projectId by this point).
+const TEST_CONFIG = {
+  cloud: { config: { projectId: PROJECT_ID } },
+  apiUrl: 'http://127.0.0.1:5002',
+  projectDir: '/tmp/omega-fixture',
+  testPaths: [],
+  emulatorPorts: { firestore: 8080, auth: 9099, hosting: 5002 },
+};
+
+function buildCommand(testConfig) {
+  const command = new TestCommand({ firebaseProjectPath: testConfig.projectDir, argv: {}, options: {} });
+
+  return command.buildTestCommand(testConfig);
+}
+
+module.exports = defineCases({
+  description: 'the test runner child is told which project it is testing',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'the-command-exports-gcloud-project-from-the-resolved-config',
+      run({ assert }) {
+        assert.match(buildCommand(TEST_CONFIG), new RegExp(`GCLOUD_PROJECT='${PROJECT_ID}'`));
+      },
+    },
+
+    {
+      name: 'the-emulator-hosts-still-ride-along-with-it',
+      run({ assert }) {
+        const command = buildCommand(TEST_CONFIG);
+
+        assert.match(command, /FIRESTORE_EMULATOR_HOST='127\.0\.0\.1:8080'/);
+        assert.match(command, /FIREBASE_AUTH_EMULATOR_HOST='127\.0\.0\.1:9099'/);
+      },
+    },
+
+    {
+      name: 'bumped-ports-and-the-project-id-travel-together',
+      run({ assert }) {
+        // The auto-start path rebuilds the command from the RESOLVED ports after
+        // boot; the project id is the same either way.
+        const command = buildCommand({
+          ...TEST_CONFIG,
+          emulatorPorts: { firestore: 8081, auth: 9100, hosting: 5003 },
+        });
+
+        assert.match(command, new RegExp(`GCLOUD_PROJECT='${PROJECT_ID}'`));
+        assert.match(command, /FIREBASE_AUTH_EMULATOR_HOST='127\.0\.0\.1:9100'/);
+      },
+    },
+
+    // ─── the stack the runner's own URL getters resolve
+    // ([#291](https://github.com/Omega-JS-Stack/omega/issues/291)) ───
+
+    {
+      name: 'the-resolved-port-map-rides-along-with-the-command',
+      run({ assert }) {
+        // Journey tests call route handlers IN-PROCESS, so the runner's Manager
+        // builds URLs from OMEGA_*_PORT exactly like a function worker does.
+        // Unset, every getter fell back to the classic defaults and answered for
+        // a stack that may not be there.
+        const command = buildCommand({
+          ...TEST_CONFIG,
+          emulatorPorts: { firestore: 8081, auth: 9100, hosting: 5003, functions: 5004 },
+        });
+
+        assert.match(command, /OMEGA_HOSTING_PORT='5003'/);
+        assert.match(command, /OMEGA_FUNCTIONS_PORT='5004'/);
+        assert.match(command, /OMEGA_FIRESTORE_PORT='8081'/);
+      },
+    },
+
+    {
+      name: 'the-https-front-is-never-handed-to-the-runner',
+      run({ assert }) {
+        // `omega emulator` defaults HTTPS on: hosting moves to an internal plain
+        // port and the mkcert proxy takes the classic one. The runner has no CA
+        // for that cert — handed the TLS port it would send the test provider's
+        // auto-webhook through the proxy and fail on the handshake, so it gets
+        // hosting's INTERNAL port and nothing else.
+        const command = buildCommand({
+          ...TEST_CONFIG,
+          apiUrl: 'http://127.0.0.1:5443',
+          emulatorPorts: { firestore: 8080, auth: 9099, hosting: 5443, https: 5002 },
+        });
+
+        assert.match(command, /OMEGA_HOSTING_PORT='5443'/);
+        assert.notMatch(command, /OMEGA_HTTPS_PORT/);
+      },
+    },
+  ],
+});

package/test/cli/test-stack-shutdown.test.js

@@ -0,0 +1,275 @@
+/**
+ * Test: the stack `omega test` starts for itself goes down on EVERY stop signal
+ * ([#722](https://github.com/Omega-JS-Stack/omega/issues/722)).
+ *
+ * `omega test` boots its own emulator when there is none to adopt, and it wired
+ * the teardown to SIGINT alone. A run stopped any other way — a supervisor's
+ * SIGTERM, a closed terminal's SIGHUP — took Node's default action instead: the
+ * CLI process died where it stood and the whole firebase tree it had spawned
+ * reparented to PID 1, exactly the [#629](https://github.com/Omega-JS-Stack/omega/issues/629)
+ * defect on the sibling path.
+ *
+ * Run: npx omega test backend:cli/test-stack-shutdown
+ *
+ * The run under test is a REAL child process, detached into its own process
+ * group: a signal is only a signal when it arrives at a process, and an
+ * in-process case can call the stop path but never prove SIGHUP reaches it. No
+ * emulator is booted — startEmulators is the one seam replaced, because what
+ * the signal path owes its caller is decided by what it does with the HANDLE,
+ * not by how the handle came to be. The test runner it spawns is a `sleep`, so
+ * the run idles the way a real one does while its suites run.
+ */
+const os = require('os');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+const jetpack = require('fs-jetpack');
+const powertools = require('node-powertools');
+
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// The run, in its own process. startEmulators hands back the same three things
+// a real boot does — a shutdown, a promise that never settles on its own (the
+// child outlives the suites), and a resolved port map — and records the one
+// thing under test: whether the teardown was reached at all.
+const SIGNAL_DRIVER = `
+const fs = require('fs');
+const [, , commandPath, emulatorPath, projectDir, statePath, readyPath] = process.argv;
+
+const TestCommand = require(commandPath);
+const EmulatorCommand = require(emulatorPath);
+
+EmulatorCommand.prototype.startEmulators = async () => ({
+  // Slow on purpose: a real teardown signals a tree and waits on ports, and a
+  // second stop signal arriving DURING it is the case the handler must survive.
+  shutdown: async () => {
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    fs.appendFileSync(statePath, 'shutdown\\n');
+  },
+  exitPromise: new Promise(() => {}),
+  emulatorPorts: { hosting: 15002, firestore: 18080, auth: 19099, ui: 14000 },
+});
+
+const command = new TestCommand({ firebaseProjectPath: projectDir, argv: {}, options: {} });
+
+// 'Logs saving to' is the last line the run prints before it settles into
+// waiting on its test child — and it prints AFTER the stop handlers are
+// registered, which is what the parent must not race. 'Shutting down' is the
+// handler's own first line, so the state file counts how many times the
+// teardown was ENTERED, not just whether it finished.
+command.log = (message) => {
+  const text = String(message);
+
+  if (/Shutting down emulator/.test(text)) fs.appendFileSync(statePath, 'teardown\\n');
+  if (/Logs saving to/.test(text)) fs.writeFileSync(readyPath, 'ready');
+};
+command.logError = () => {};
+command.logWarning = () => {};
+command.startLane = async () => ({ env: {}, stop: () => {} });
+command.buildTestCommand = () => 'sleep 30';
+
+command.runEmulatorTests({}, projectDir).catch(() => {});
+`;
+
+/**
+ * Poll until `check` passes or the window closes.
+ * @param {Function} check - Returns truthy when the wait is over.
+ * @param {number} timeoutMs - How long to keep looking.
+ * @returns {Promise<boolean>} Whether it passed inside the window.
+ */
+async function waitUntil(check, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    if (check()) {
+      return true;
+    }
+
+    await powertools.wait(50);
+  }
+
+  return check();
+}
+
+/**
+ * The command line a pid is running right now, or '' when it is gone.
+ * @param {number} pid - The pid to read.
+ * @returns {string}
+ */
+function commandOf(pid) {
+  try {
+    return execSync(`ps -o command= -p ${Number(pid)} 2>/dev/null`, { encoding: 'utf8' }).trim();
+  } catch (error) {
+    return '';
+  }
+}
+
+/**
+ * The run's ONE child: the test runner it spawned. Read from the process table
+ * rather than reported by the driver, because what is on trial is whether a
+ * real process is still there after the run is gone.
+ * @param {number} pid - The run's pid.
+ * @returns {number|null}
+ */
+function testRunnerPid(pid) {
+  try {
+    const found = execSync(`pgrep -P ${Number(pid)} 2>/dev/null`, { encoding: 'utf8' }).trim().split('\n')[0];
+    return found ? Number(found) : null;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Boot the driver and wait for the run to reach the point where it is waiting
+ * on its test child — stop handlers registered, stack "up".
+ */
+async function bootedRun() {
+  const dir = path.join(os.tmpdir(), `omega-test-signal-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  const statePath = path.join(dir, 'state.txt');
+  const readyPath = path.join(dir, 'ready.txt');
+
+  // getLogsPath() writes test.log into dist/ — the one real directory the run
+  // touches, inside this throwaway project.
+  jetpack.dir(path.join(dir, 'dist'));
+  jetpack.write(path.join(dir, 'driver.js'), SIGNAL_DRIVER);
+
+  // Detached: the run gets its OWN process group, so the signal below lands on
+  // that ONE process and nothing else — the strictly harder case, and the one
+  // a supervisor's stop and a closed terminal both produce.
+  const child = spawn(process.execPath, [
+    path.join(dir, 'driver.js'),
+    require.resolve('../../dist/cli/commands/test.js'),
+    require.resolve('../../dist/cli/commands/emulator.js'),
+    dir,
+    statePath,
+    readyPath,
+  ], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+
+  let output = '';
+  child.stdout.on('data', (data) => { output += data.toString(); });
+  child.stderr.on('data', (data) => { output += data.toString(); });
+
+  let exit = null;
+  child.once('exit', (code, signal) => { exit = { code: code, signal: signal }; });
+
+  const ready = await waitUntil(() => jetpack.exists(readyPath), 60000);
+
+  // The test runner is spawned on the very next line the run executes, and it
+  // is the half of the stack the signal does NOT reach on its own.
+  let runnerPid = null;
+  await waitUntil(() => {
+    runnerPid = testRunnerPid(child.pid);
+    return runnerPid !== null;
+  }, 30000);
+
+  return {
+    child: child,
+    ready: ready,
+    runnerPid: runnerPid,
+    output: () => output,
+    exit: () => exit,
+    state: () => String(jetpack.read(statePath) || ''),
+    cleanup: () => {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch (e) { /* already gone */ }
+      try { process.kill(child.pid, 'SIGKILL'); } catch (e) { /* already gone */ }
+      jetpack.remove(dir);
+    },
+  };
+}
+
+/**
+ * Boot the run, signal it, and prove it took its teardown instead of dying.
+ * The only process signalled is the one this case spawned.
+ * @param {object} assert - The case assertions.
+ * @param {string} signal - The stop signal under test.
+ */
+async function tearsDownOn(assert, signal) {
+  const run = await bootedRun();
+
+  try {
+    assert.equal(run.ready, true, `the run must come up before it can be stopped: ${run.output()}`);
+    assert.equal(typeof run.runnerPid, 'number', `the run must reach its test runner before it is stopped: ${run.output()}`);
+
+    process.kill(run.child.pid, signal);
+
+    assert.equal(await waitUntil(() => run.exit() !== null, 30000), true, `the run must exit on ${signal}: ${run.output()}`);
+    assert.equal(run.state().includes('shutdown'), true, `${signal} must run the emulator teardown, not Node's default action`);
+    assert.equal(run.exit().code, 130, `a signalled run exits 130 on ${signal}, got ${JSON.stringify(run.exit())}`);
+
+    // The signal is DIRECTED at the CLI pid, so it never reaches the test
+    // runner: unless the teardown takes the child down itself, the suites keep
+    // running orphaned to PID 1 long after the run that owns them is gone.
+    const runnerGone = await waitUntil(() => !commandOf(run.runnerPid), 10000);
+    assert.equal(runnerGone, true, `${signal} must take the test runner down too — pid ${run.runnerPid} still running ${JSON.stringify(commandOf(run.runnerPid))}`);
+  } finally {
+    run.cleanup();
+  }
+}
+
+module.exports = defineCases({
+  description: 'omega test: the auto-started emulator stack goes down on every stop signal',
+  type: 'group',
+  timeout: 120000,
+
+  tests: [
+    {
+      name: 'ctrl-c-tears-the-auto-started-stack-down',
+      timeout: 120000,
+      async run({ assert }) {
+        // The one signal this path always handled — it must survive the trio.
+        await tearsDownOn(assert, 'SIGINT');
+      },
+    },
+
+    {
+      name: 'a-programmatic-stop-tears-the-auto-started-stack-down',
+      timeout: 120000,
+      async run({ assert }) {
+        // SIGTERM is how anything but a terminal stops a run: a supervisor, a
+        // harness, `kill` with no flag. It killed the CLI outright and left the
+        // emulator it had spawned behind.
+        await tearsDownOn(assert, 'SIGTERM');
+      },
+    },
+
+    {
+      name: 'a-closed-terminal-tears-the-auto-started-stack-down',
+      timeout: 120000,
+      async run({ assert }) {
+        // Closing the window on a running `omega test` sends SIGHUP, and it
+        // orphaned the same tree onto PID 1.
+        await tearsDownOn(assert, 'SIGHUP');
+      },
+    },
+
+    {
+      name: 'a-second-stop-signal-does-not-start-a-second-teardown',
+      timeout: 120000,
+      async run({ assert }) {
+        // Impatient Ctrl+C, and a supervisor's escalation, both send a second
+        // signal while the first teardown is still running. Unguarded, the
+        // handler runs again underneath it and tears the same stack down twice.
+        const run = await bootedRun();
+
+        try {
+          assert.equal(run.ready, true, `the run must come up before it can be stopped: ${run.output()}`);
+
+          process.kill(run.child.pid, 'SIGINT');
+          await powertools.wait(100);
+
+          assert.equal(run.exit(), null, 'the second signal must land while the first teardown is still running');
+          try { process.kill(run.child.pid, 'SIGINT'); } catch (e) { /* raced the exit */ }
+
+          assert.equal(await waitUntil(() => run.exit() !== null, 30000), true, `the run must exit: ${run.output()}`);
+          assert.equal(run.state().split('teardown').length - 1, 1, `the teardown is ENTERED once, got ${JSON.stringify(run.state())}`);
+          assert.equal(run.state().includes('shutdown'), true, `the one teardown still runs to completion, got ${JSON.stringify(run.state())}`);
+        } finally {
+          run.cleanup();
+        }
+      },
+    },
+  ],
+});