create-stitchkit 0.3.3 → 0.4.1

package/template/scripts/release-steps.ts

@@ -0,0 +1,112 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ProjectDeclaration } from 'stitchkit/declaration';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { assertArtifactMatchesSource } from './build-stamp';
+import { inheritToolingEnvironment } from './tooling-env';
+
+const root = resolve(import.meta.dir, '..');
+
+/**
+ * Bringing this deployment to this source — the steps the DECLARATION says
+ * must happen once, before any role starts.
+ *
+ * The declaration says what a migration *is* (engine, root, lockfile), not what
+ * command to run for it. That split is the point: an outside deployment tool
+ * reads the bytes and decides for itself — exact contents, admission verdict,
+ * whether a preflight is needed at all — while the project keeps the one command
+ * that applies them here. Neither side has to learn the other's vocabulary.
+ */
+const MIGRATION_COMMANDS: Record<string, string[]> = {
+  prisma: ['bun', 'run', 'db:deploy'],
+};
+
+/**
+ * The command that applies this project's declared migrations, or `undefined`
+ * when it declares none — absent means "there are none", not "we forgot to say".
+ *
+ * An engine with no command here is refused rather than skipped: silently not
+ * migrating is the failure that leaves a deployment running against the wrong
+ * schema.
+ */
+/**
+ * A declared command as an operator can retype it.
+ *
+ * `${command}` on a `{ executable, args }` object prints `[object Object]`, so
+ * the one diagnostic that exists to tell an operator what to run told them
+ * nothing. Quoting is deliberate: an argument with a space has to survive being
+ * read back.
+ */
+export function formatCommand(command: { executable: string; args: string[] }): string {
+  return [command.executable, ...command.args]
+    .map((part) => (/[\s"']/.test(part) ? JSON.stringify(part) : part))
+    .join(' ');
+}
+
+export function migrationCommandFor(
+  declaration: ProjectDeclaration = appDeclaration,
+): string[] | undefined {
+  const { migrations } = declaration.release;
+  if (!migrations) return undefined;
+
+  const command = MIGRATION_COMMANDS[migrations.engine];
+  if (!command) {
+    throw new Error(
+      `project.json declares migrations for "${migrations.engine}", which this project has no command for.`,
+    );
+  }
+  // Both declared paths are checked. The lockfile is what tells a reader the
+  // migrations belong to one lineage; declaring it and then not looking at it
+  // is how a declaration starts describing a tree that is not there.
+  const declaredPaths: Array<[string, string]> = [
+    ['root', migrations.root],
+    ['lockfile', migrations.lockfile],
+  ];
+  for (const [label, path] of declaredPaths) {
+    if (!existsSync(resolve(root, path))) {
+      throw new Error(`Declared migration ${label} ${path} does not exist.`);
+    }
+  }
+  return command;
+}
+
+/**
+ * Everything the declaration says building produces must exist before roles
+ * start.
+ *
+ * Derived from `build.artifacts` rather than from a list kept here, so an
+ * artifact added to the declaration is covered without a second edit — and the
+ * failure names the missing path instead of surfacing as a module-not-found
+ * inside a supervised process, where nobody reads it.
+ */
+export function assertBuildArtifacts(declaration: ProjectDeclaration = appDeclaration): void {
+  const build = declaration.build;
+  if (!build) return;
+  const missing = build.artifacts.filter((artifact) => !existsSync(resolve(root, artifact)));
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing build artifacts: ${missing.join(', ')} — run \`${formatCommand(build.command)}\` first.`,
+    );
+  }
+  // Present is not current. Without this, a release applies THIS source's
+  // migrations and then starts the previous source's artifact.
+  assertArtifactMatchesSource(root);
+}
+
+export async function runDeclaredReleaseSteps(
+  environment?: Record<string, string>,
+): Promise<void> {
+  const command = migrationCommandFor();
+  if (!command) return;
+
+  const child = Bun.spawn(command, {
+    cwd: root,
+    env: environment ? inheritToolingEnvironment(environment) : undefined,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  if ((await child.exited) !== 0) {
+    throw new Error(`${command.join(' ')} failed`);
+  }
+}

package/template/scripts/release.ts

@@ -0,0 +1,38 @@
+import { resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
+import { assertBuildArtifacts, runDeclaredReleaseSteps } from './release-steps';
+import { deploymentEnvironment } from './tooling-env';
+
+/**
+ * Bring this deployment to this source, then hand the roles to the supervisor.
+ *
+ * The order is the declaration's, not this file's: build artifacts must exist,
+ * declared release steps run once, and only then do roles start. Nothing here
+ * repeats what `project.json` already says — the migration engine, the artifact
+ * paths and the roles all come from it, and the supervision file this ends with
+ * is generated from it too.
+ */
+const root = resolve(import.meta.dir, '..');
+
+assertBuildArtifacts();
+await runDeclaredReleaseSteps();
+
+const supervisor = Bun.spawn(['pm2', 'startOrReload', 'ecosystem.config.cjs', '--update-env'], {
+  cwd: root,
+  stdin: 'inherit',
+  stdout: 'inherit',
+  stderr: 'inherit',
+});
+const exitCode = await supervisor.exited;
+if (exitCode !== 0) process.exit(exitCode);
+
+// Under supervision is not yet serving. A release that returns before the
+// roles answer makes every command after it — a smoke, a health check, a
+// rollout step — race the application it just started.
+const roles = declaredRoleReadiness(appDeclaration, deploymentEnvironment(root));
+await awaitRolesAnswering(roles);
+for (const role of appDeclaration.roles) {
+  console.log(`${appDeclaration.identity.slug}-${role.name} is under supervision`);
+}
+for (const role of roles) console.log(`${role.name}: ${role.url}`);

package/template/scripts/runtime-smoke.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { declaredRoleReadiness } from './readiness';
+import { planPortabilityCheck } from './web-surface-smoke';
+
+const dialled = 'http://127.0.0.1:3210';
+
+describe('the portability check dials addresses the deployment claims', () => {
+  test('two claimed addresses besides the dialled one become the two probes', () => {
+    const plan = planPortabilityCheck(dialled, {
+      hosts: '127.0.0.1:3210,alpha.example,beta.example:8443',
+    });
+    expect(plan.kind).toBe('check');
+    if (plan.kind !== 'check') return;
+    expect(plan.addresses).toEqual([
+      { host: 'alpha.example', proto: 'https' },
+      { host: 'beta.example:8443', proto: 'http' },
+    ]);
+  });
+
+  test('a deployment with nothing but its own address is told what to add', () => {
+    // The reported failure, from the other side: the check used to carry two
+    // fixture hosts of its own, so a deployment that had never been told about
+    // them refused the request and the gate showed a bare 500.
+    const plan = planPortabilityCheck(dialled, { hosts: '127.0.0.1:3210' });
+    expect(plan.kind).toBe('refuse');
+    if (plan.kind !== 'refuse') return;
+    expect(plan.reason).toContain(
+      'PUBLIC_WEB_HOSTS=127.0.0.1:3210,alpha.example,beta.example:8443',
+    );
+    expect(plan.reason).toContain('bun run dev');
+  });
+
+  test('a deployment that claims nothing at all is refused the same way', () => {
+    const plan = planPortabilityCheck(dialled, {});
+    expect(plan.kind).toBe('refuse');
+    if (plan.kind !== 'refuse') return;
+    expect(plan.reason).toContain('no host at all');
+  });
+
+  test('a pinned public origin is a skip with a reason, not a failure', () => {
+    // PUBLIC_WEB_ORIGIN short-circuits the request-derived origin, so the
+    // deployment answers with one address whatever it is asked on. That is a
+    // legitimate configuration; failing it would be a false diagnosis.
+    const plan = planPortabilityCheck(dialled, {
+      origin: 'https://example.com',
+      hosts: '127.0.0.1:3210,alpha.example,beta.example:8443',
+    });
+    expect(plan.kind).toBe('skip');
+    if (plan.kind !== 'skip') return;
+    expect(plan.reason).toContain('https://example.com');
+  });
+
+  test('the forged host is never one the deployment claims', () => {
+    // Otherwise the refusal the check exists to provoke never happens, and an
+    // assertion that cannot fail is worse than no assertion.
+    const plan = planPortabilityCheck(dialled, {
+      hosts: '127.0.0.1:3210,alpha.example,beta.example:8443,attacker.example',
+    });
+    expect(plan.kind).toBe('check');
+    if (plan.kind !== 'check') return;
+    expect(plan.forgedHost).not.toBe('attacker.example');
+    expect(plan.forgedHost).toBe('attacker-1.invalid');
+  });
+
+  test('one host written twice is one address, not two', () => {
+    // The count decides whether the property can be proved at all. Without
+    // deduplication a duplicate entry passed as a second address and the check
+    // compared the deployment with itself — a proof that cannot fail.
+    const plan = planPortabilityCheck(dialled, {
+      hosts: '127.0.0.1:3210,alpha.example,alpha.example',
+    });
+    expect(plan.kind).toBe('refuse');
+  });
+
+  test('the claimed list is matched case-insensitively, like the policy that reads it', () => {
+    const plan = planPortabilityCheck('http://127.0.0.1:3210', {
+      hosts: ' 127.0.0.1:3210 , Alpha.Example , BETA.example:8443 ',
+    });
+    expect(plan.kind).toBe('check');
+    if (plan.kind !== 'check') return;
+    expect(plan.addresses.map((address) => address.host)).toEqual([
+      'alpha.example',
+      'beta.example:8443',
+    ]);
+  });
+});
+
+describe('a gate list is not a deploy instruction', () => {
+  // `runtime:smoke` and `e2e` check a running deployment, so the list has to
+  // bring one up — and the wrong way to do that shipped once already:
+  // `pm2:prod` applies the declared migrations and reloads the deployment the
+  // developer is running. A gate creates and destroys its OWN deployment, and
+  // that is `acceptance:local`.
+  const root = resolve(import.meta.dir, '..');
+  const guidance = ['README.md', 'AGENTS.md'];
+
+  for (const file of guidance) {
+    const text = readFileSync(resolve(root, file), 'utf8');
+    const blocks = [...text.matchAll(/```bash\n([\s\S]*?)```/g)].map(([, body]) => body ?? '');
+    const gates = blocks.filter((body) => body.includes('bun run check'));
+
+    test(`${file} lists gates`, () => {
+      expect(gates.length).toBeGreaterThan(0);
+    });
+
+    test(`${file} puts no deployment command in the gate list`, () => {
+      for (const body of gates) {
+        expect(body).not.toContain('pm2:prod');
+      }
+    });
+
+    test(`${file} brings a deployment up before the checks that dial one`, () => {
+      for (const body of gates) {
+        const lines = body.split('\n').map((line) => line.trim());
+        const dialling = ['bun run runtime:smoke', 'bun run e2e'].filter((command) =>
+          lines.includes(command),
+        );
+        if (dialling.length === 0) {
+          expect(lines).toContain('bun run acceptance:local');
+          continue;
+        }
+        const start = lines.indexOf('bun run acceptance:local');
+        expect(start).toBeGreaterThanOrEqual(0);
+        for (const command of dialling) expect(start).toBeLessThan(lines.indexOf(command));
+      }
+    });
+
+    test(`${file} never tells anyone to delete every supervised application`, () => {
+      // `pm2 delete all` empties the daemon it is pointed at, including
+      // applications that have nothing to do with this project.
+      expect(text).not.toContain('pm2 delete all');
+    });
+  }
+});
+
+describe('a role is ready when it answers, not when it is spawned', () => {
+  const environment = { API_PORT: '3211', WEB_PORT: '3210', BIND_HOST: '127.0.0.1' };
+
+  test('every listening role gets its declared readiness address', () => {
+    expect(declaredRoleReadiness(appDeclaration, environment)).toEqual([
+      { name: 'api', url: 'http://127.0.0.1:3211/health' },
+      { name: 'web', url: 'http://127.0.0.1:3210/' },
+    ]);
+  });
+
+  test('a bind address of every interface is dialled on loopback', () => {
+    // `0.0.0.0` is what a role BINDS. Dialling it as an address is a different
+    // question, and loopback is the one this machine can always answer.
+    const addresses = declaredRoleReadiness(appDeclaration, {
+      ...environment,
+      BIND_HOST: '0.0.0.0',
+    });
+    expect(addresses.every((role) => role.url.startsWith('http://127.0.0.1:'))).toBe(true);
+  });
+
+  test('an IPv6 bind address is bracketed, or it is not a URL at all', () => {
+    // `http://::1:3211/health` cannot be parsed as an address with a port, so
+    // the wait failed on the spelling instead of on the role.
+    const addresses = declaredRoleReadiness(appDeclaration, {
+      ...environment,
+      BIND_HOST: '::1',
+    });
+    expect(addresses.map((role) => role.url)).toEqual([
+      'http://[::1]:3211/health',
+      'http://[::1]:3210/',
+    ]);
+    for (const role of addresses) expect(() => new URL(role.url)).not.toThrow();
+  });
+
+  test('a declared listener with no port is an error, not a silent skip', () => {
+    expect(() =>
+      declaredRoleReadiness(appDeclaration, { ...environment, WEB_PORT: undefined }),
+    ).toThrow(/WEB_PORT/);
+  });
+});

package/template/scripts/runtime-smoke.ts

@@ -1,15 +1,25 @@
 import { systemContract } from '@app/shared';
 import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
+import { assertDeploymentIsAnswering } from './deployment-preflight';
 import { runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
-import { assertPublicWebSurface } from './web-surface-smoke';
+import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-surface-smoke';
 
 const toolingEnv = loadToolingEnv();
-const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
+const apiOrigin = toolingEnv.SMOKE_API_ORIGIN;
+
+await assertDeploymentIsAnswering({
+  'the API role': apiOrigin,
+  'the web role': toolingEnv.SMOKE_WEB_ORIGIN,
+});
 
 async function json(path: string): Promise<unknown> {
-  const response = await fetch(`${apiOrigin}${path}`);
+  // Bounded: an endpoint that accepts the connection and never answers must
+  // turn this gate red, not hang it with no output and no deadline.
+  const response = await fetch(`${apiOrigin}${path}`, {
+    signal: AbortSignal.timeout(30_000),
+  });
   if (!response.ok) throw new Error(`GET ${path} returned ${response.status}`);
   return response.json();
 }
@@ -28,6 +38,12 @@ if (!Object.keys(openApi.paths).includes('/api/system/status')) {
 }
 
 await runSurfaceConformance({ apiOrigin });
-await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
+await assertPublicWebSurface(toolingEnv.SMOKE_WEB_ORIGIN);
+await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN, {
+  origin: toolingEnv.PUBLIC_WEB_ORIGIN,
+  hosts: toolingEnv.PUBLIC_WEB_HOSTS,
+});
 
-console.log('Runtime HTTP, typed client, OpenAPI, MCP and public web smoke passed');
+console.log(
+  'Runtime HTTP, typed client, OpenAPI, MCP, public web and placement-free artifact smoke passed',
+);

package/template/scripts/serve-mode.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+/**
+ * The web role refuses a mode it does not understand.
+ *
+ * `argv[2] === 'development' ? 'dev' : 'start'` meant a typo, an empty string
+ * and a missing argument all became production in silence — the one decision
+ * that changes whether the role serves a build or compiles on demand. Run as a
+ * real process, because the failure has to happen before Next is spawned.
+ */
+const serve = join(import.meta.dir, '../packages/frontend/scripts/serve.ts');
+
+async function refusal(argv: string[]): Promise<{ code: number; stderr: string }> {
+  const child = Bun.spawn(['bun', serve, ...argv], {
+    cwd: join(import.meta.dir, '../packages/frontend'),
+    env: { ...Bun.env, WEB_PORT: '3210', BIND_HOST: '127.0.0.1' },
+    stdout: 'ignore',
+    stderr: 'pipe',
+  });
+  const [stderr, code] = await Promise.all([new Response(child.stderr).text(), child.exited]);
+  return { code, stderr };
+}
+
+test('a misspelled mode is refused, not treated as production', async () => {
+  const { code, stderr } = await refusal(['produciton']);
+  expect(code).not.toBe(0);
+  expect(stderr).toContain('Run mode must be "development" or "production"');
+  expect(stderr).toContain('produciton');
+}, 30_000);
+
+test('a missing mode is refused', async () => {
+  const { code, stderr } = await refusal([]);
+  expect(code).not.toBe(0);
+  expect(stderr).toContain('received nothing');
+}, 30_000);

package/template/scripts/shutdown-budget.fixture.ts

@@ -0,0 +1,29 @@
+/**
+ * A role whose cleanup will not complete, as a real process.
+ *
+ * The regression this serves cannot be written against a promise. The defect
+ * was never "the helper resolved late" — it was that the role set
+ * `process.exitCode` and then waited for an event loop something was still
+ * holding, so the process lived until the supervisor's SIGKILL: exactly the
+ * ending the cleanup budget exists to prevent. Only a process can show that.
+ *
+ * The interval below is the held handle. Nothing ever clears it, so this
+ * process ends only if something ends it — which is the assertion.
+ */
+import { closeWithinBudget, concludeShutdown } from '../packages/backend/src/cleanup';
+
+setInterval(() => undefined, 1_000);
+
+const budgetMs = Number(Bun.argv[2] ?? '200');
+const mode = Bun.argv[3] ?? 'hang';
+
+const steps = {
+  hang: { name: 'database', close: () => new Promise<void>(() => undefined) },
+  throw: { name: 'database', close: () => Promise.reject(new Error('pool already gone')) },
+  clean: { name: 'database', close: () => Promise.resolve() },
+};
+const step = steps[mode === 'throw' ? 'throw' : mode === 'clean' ? 'clean' : 'hang'];
+
+const result = await closeWithinBudget([step], budgetMs);
+console.log(`FIXTURE ${JSON.stringify({ unfinished: result.unfinished })}`);
+concludeShutdown(result, true);

package/template/scripts/shutdown-budget.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  type CleanupResult,
+  closeWithinBudget,
+  concludeShutdown,
+} from '../packages/backend/src/cleanup';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { CLEANUP_BUDGET_MS, FORCE_BUDGET_MS } from '../packages/config/src/shutdown';
+import { terminationBudgetMs } from './declaration';
+
+describe('the termination budget is an upper bound, not an estimate', () => {
+  test('the budget is exactly the three bounded parts', () => {
+    for (const role of appDeclaration.roles) {
+      expect(terminationBudgetMs(role)).toBe(
+        role.drainFloorMs + FORCE_BUDGET_MS + CLEANUP_BUDGET_MS,
+      );
+    }
+  });
+
+  test('a cleanup that finishes reports nothing unfinished', async () => {
+    const closed: string[] = [];
+    const result = await closeWithinBudget([
+      { name: 'MCP', close: async () => closed.push('MCP') },
+      { name: 'database', close: async () => closed.push('database') },
+    ]);
+    expect(closed).toEqual(['MCP', 'database']);
+    expect(result.unfinished).toEqual([]);
+  });
+
+  test('a close that hangs stops being waited for, and is named', async () => {
+    // The defect this exists for: the drain had a deadline, the closes after it
+    // had none, so a hung MCP session or database pool ran past the very kill
+    // timeout the budget had told the supervisor to allow — turning an orderly
+    // shutdown into the SIGKILL that runs no cleanup at all.
+    const result = await closeWithinBudget(
+      [{ name: 'MCP', close: () => new Promise<void>(() => undefined) }],
+      25,
+    );
+    expect(result.unfinished).toEqual(['MCP']);
+    expect(result.durationMs).toBeLessThan(CLEANUP_BUDGET_MS);
+  });
+
+  test('the steps share one budget rather than each getting a full one', async () => {
+    const result = await closeWithinBudget(
+      [
+        { name: 'MCP', close: () => new Promise<void>(() => undefined) },
+        { name: 'database', close: () => new Promise<void>(() => undefined) },
+      ],
+      25,
+    );
+    expect(result.unfinished).toEqual(['MCP', 'database']);
+    // Two steps, one budget: about one budget of wall clock, not two.
+    expect(result.durationMs).toBeLessThan(50);
+  });
+
+  test('a close that fails is a failure, and keeps its cause', async () => {
+    // It used to be swallowed into `undefined` with the note that the budget is
+    // about time. The budget is — but a close that throws is a shutdown that
+    // did not happen, and reporting it as a clean exit with the reason gone is
+    // how a broken shutdown looks exactly like a working one.
+    const result = await closeWithinBudget([
+      { name: 'database', close: () => Promise.reject(new Error('pool already gone')) },
+    ]);
+    expect(result.unfinished).toEqual([]);
+    expect(result.failed.map((failure) => failure.name)).toEqual(['database']);
+    expect(result.failed[0]?.cause).toBeInstanceOf(Error);
+  });
+
+  test('a cleanup that completed is a zero exit and no forced ending', () => {
+    let exited: number | undefined;
+    concludeShutdown({ unfinished: [], failed: [], durationMs: 3 }, true, (code) => {
+      exited = code;
+    });
+    expect(process.exitCode).toBe(0);
+    expect(exited).toBeUndefined();
+    process.exitCode = 0;
+  });
+
+  test('an unfinished step and a failed one both end the process non-zero', () => {
+    const endings: Array<[string, CleanupResult]> = [
+      ['unfinished', { unfinished: ['database'], failed: [], durationMs: 5 }],
+      [
+        'failed',
+        {
+          unfinished: [],
+          failed: [{ name: 'database', cause: new Error('pool already gone') }],
+          durationMs: 5,
+        },
+      ],
+    ];
+    for (const [label, result] of endings) {
+      let exited: number | undefined;
+      concludeShutdown(result, true, (code) => {
+        exited = code;
+      });
+      expect(`${label}:${exited}`).toBe(`${label}:1`);
+    }
+    process.exitCode = 0;
+  });
+
+  test('the role bounds its own cleanup rather than awaiting it bare', () => {
+    // One number, two readers — and the reader that matters is the role. An
+    // `await mcp.close()` here with nothing around it is the whole defect.
+    const source = readFileSync(
+      resolve(import.meta.dir, '../packages/backend/src/index.ts'),
+      'utf8',
+    );
+    expect(source).toContain('closeWithinBudget');
+    expect(source).not.toMatch(/await mcp\.close\(\);/);
+    expect(source).not.toMatch(/await prisma\.\$disconnect\(\);/);
+  });
+});
+
+describe('a spent budget ends the process itself', () => {
+  const fixture = resolve(import.meta.dir, 'shutdown-budget.fixture.ts');
+
+  async function runFixture(mode: string, budgetMs: number, waitMs: number) {
+    const child = Bun.spawn(['bun', fixture, String(budgetMs), mode], {
+      cwd: resolve(import.meta.dir, '..'),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const startedAt = Date.now();
+    const timeout = Bun.sleep(waitMs).then(() => 'timeout');
+    const finished = await Promise.race([child.exited, timeout]);
+    const elapsed = Date.now() - startedAt;
+    if (finished === 'timeout') {
+      child.kill('SIGKILL');
+      await child.exited;
+      return { exitCode: undefined, elapsed, stdout: '', stderr: '' };
+    }
+    const [stdout, stderr] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    return { exitCode: finished, elapsed, stdout, stderr };
+  }
+
+  test('a role whose close never finishes exits anyway, and says so', async () => {
+    const run = await runFixture('hang', 200, 8_000);
+    expect(run.exitCode).toBe(1);
+    expect(run.stderr).toContain('the cleanup budget is spent, exiting anyway');
+    // Well inside a supervisor's kill timeout, which is what the declared
+    // termination budget promises this stays inside.
+    expect(run.elapsed).toBeLessThan(5_000);
+  }, 20_000);
+
+  test('a role whose close throws exits non-zero, with the cause', async () => {
+    const run = await runFixture('throw', 200, 8_000);
+    expect(run.exitCode).toBe(1);
+    expect(run.stderr).toContain('Shutdown could not close database');
+    expect(run.stderr).toContain('pool already gone');
+  }, 20_000);
+
+  test('the held handle really does hold — without it the test proves nothing', async () => {
+    // Falsification. If this process ended on its own, the two assertions above
+    // would pass with `concludeShutdown` deleted, and the regression would be
+    // measuring the absence of work rather than the presence of an ending.
+    const run = await runFixture('clean', 200, 1_500);
+    expect(run.exitCode).toBeUndefined();
+  }, 20_000);
+});