@homeflare/alchemy 0.5.0 → 0.6.0

package/src/launchd/job-identity.test.ts

@@ -0,0 +1,147 @@
+/**
+ * LaunchdJob's identity edges against the fake host: renames (a delete-first replace), jobs this
+ * resource does not own, a gui domain with no login session, and what a failure leaves behind.
+ *
+ * ★ Split from job-lifecycle.test.ts, which covers the ordinary create / update / delete path.
+ *   Every test here is a way to end up with NOTHING running, or TWO copies running.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeRunner } from './fake-runner.ts';
+import type { LaunchdJobProps } from './job-form.ts';
+import { deleteJob, diffJob, readJob, reconcileJob, replaceDiff } from './job-lifecycle.ts';
+
+const DAEMON = '/Library/LaunchDaemons/com.example.job.plist';
+const RENAMED = '/Library/LaunchDaemons/com.example.renamed.plist';
+const AGENT = '/Users/someone/Library/LaunchAgents/com.example.job.plist';
+
+const job: LaunchdJobProps = {
+  domain: 'system',
+  label: 'com.example.job',
+  programArguments: ['/usr/local/bin/job'],
+};
+const renamed: LaunchdJobProps = { ...job, label: 'com.example.renamed' };
+
+const host = (euid = 0) =>
+  fakeRunner({
+    dirs: { '/Library/LaunchDaemons': 0, '/Users/someone/Library/LaunchAgents': 501 },
+    euid,
+    users: { someone: { gid: 20, home: '/Users/someone', uid: 501 } },
+  });
+
+const verbs = (calls: string[][]) =>
+  calls
+    .map((call) => (call[0] === 'write' ? 'write' : call[1]))
+    .filter((verb) => verb !== 'print' && verb !== 'print-disabled');
+
+describe('a rename is refused at PLAN time for anything its reconcile would refuse', () => {
+  // ★ The engine deletes the old job before reconciling the new one (deleteFirst), so each of
+  //   these, caught only at reconcile, would leave nothing running.
+  test('an invalid or reserved new label', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    const bad = { ...job, label: 'org.nixos.job' };
+    await expect(diffJob(fake.runner, bad, output)).rejects.toThrow('another tool owns');
+    await expect(replaceDiff(fake.runner, bad, undefined, output)).rejects.toThrow('another tool');
+  });
+
+  test('a new domain the deployer may not write', async () => {
+    const fake = host(501);
+    const agent = { ...job, domain: 'gui/501' } as const;
+    const output = await reconcileJob(fake.runner, agent, undefined);
+    await expect(diffJob(fake.runner, job, output)).rejects.toThrow('needs root');
+    expect(fake.loaded.has('gui/501/com.example.job')).toBe(true);
+  });
+
+  test('a disabled new label', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.disabled.add('system/com.example.renamed');
+    await expect(diffJob(fake.runner, renamed, output)).rejects.toThrow('launchctl enable');
+  });
+
+  test('a new label someone else already loaded', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.loaded.set('system/com.example.renamed', 77);
+    await expect(diffJob(fake.runner, renamed, output)).rejects.toThrow('not this resource');
+    expect(fake.loaded.get('system/com.example.renamed')).toBe(77);
+  });
+
+  test('a clean rename plans a delete-first replace', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    expect(await diffJob(fake.runner, renamed, output)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+  });
+});
+
+describe('a rename that reaches reconcile as an update', () => {
+  test('boots out and removes the old job BEFORE bootstrapping the new one', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.calls.length = 0;
+    const next = await reconcileJob(fake.runner, renamed, output);
+    expect(verbs(fake.calls)).toEqual(['bootout', 'write', 'bootstrap']);
+    expect(fake.files.has(DAEMON)).toBe(false);
+    expect(fake.loaded.has('system/com.example.job')).toBe(false);
+    expect(next).toMatchObject({ loaded: true, plistPath: RENAMED });
+  });
+
+  test('never boots out a job it does not own under the new label', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.loaded.set('system/com.example.renamed', 77);
+    await expect(reconcileJob(fake.runner, renamed, output)).rejects.toThrow('not this resource');
+    expect(fake.loaded.has('system/com.example.job')).toBe(true);
+    expect(fake.loaded.get('system/com.example.renamed')).toBe(77);
+  });
+});
+
+describe('a job still running its OLD config is not mistaken for converged', () => {
+  test('write landed, bootout failed: the next deploy restarts it', async () => {
+    const fake = host();
+    const v1 = await reconcileJob(fake.runner, job, undefined);
+    fake.state.bootoutKeepsJob = true;
+    const v2 = { ...job, runAtLoad: true };
+    await expect(reconcileJob(fake.runner, v2, v1)).rejects.toThrow('bootout');
+    // The v2 plist is on disk and the v1 job is loaded: both look converged. Only state knows.
+    fake.state.bootoutKeepsJob = false;
+    fake.calls.length = 0;
+    const after = await reconcileJob(fake.runner, v2, v1);
+    expect(verbs(fake.calls)).toEqual(['write', 'bootout', 'bootstrap']);
+    expect(after.pid).not.toBe(v1.pid);
+  });
+});
+
+describe('a failed first bootstrap leaves nothing behind', () => {
+  test('the plist it wrote is removed, so the next plan does not find it Unowned', async () => {
+    const fake = host();
+    fake.state.bootstrapFailure = { exitCode: 5, stderr: 'Bootstrap failed: 5', stdout: '' };
+    await expect(reconcileJob(fake.runner, job, undefined)).rejects.toThrow('removed again');
+    expect(fake.files.has(DAEMON)).toBe(false);
+    expect(await readJob(fake.runner, job)).toBeUndefined();
+  });
+});
+
+describe('a gui domain with no login session', () => {
+  const agent = { ...job, domain: 'gui/501' } as const;
+
+  test('reconcile refuses before writing anything', async () => {
+    const fake = host(501);
+    fake.state.loggedOut.add(501);
+    await expect(reconcileJob(fake.runner, agent, undefined)).rejects.toThrow('no login session');
+    expect(fake.files.has(AGENT)).toBe(false);
+  });
+
+  test('delete still removes the plist, so launchd cannot load it at the next login', async () => {
+    const fake = host(501);
+    const output = await reconcileJob(fake.runner, agent, undefined);
+    fake.loaded.clear();
+    fake.state.loggedOut.add(501);
+    await deleteJob(fake.runner, output);
+    expect(fake.files.has(AGENT)).toBe(false);
+    expect(await readJob(fake.runner, agent)).toBeUndefined();
+  });
+});

package/src/launchd/job-lifecycle.test.ts

@@ -0,0 +1,220 @@
+/**
+ * LaunchdJob's lifecycle against the fake host: no real launchctl, no real writes.
+ *
+ * ★ The assertions are on the SEQUENCE of host calls, because the ordering is the design — write
+ *   before bootout before bootstrap, and nothing at all when the host is already converged.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeRunner } from './fake-runner.ts';
+import type { LaunchdJobProps } from './job-form.ts';
+import { deleteJob, diffJob, readJob, reconcileJob } from './job-lifecycle.ts';
+
+const DAEMON = '/Library/LaunchDaemons/com.example.job.plist';
+const AGENT = '/Users/someone/Library/LaunchAgents/com.example.job.plist';
+
+const job: LaunchdJobProps = {
+  domain: 'system',
+  keepAlive: true,
+  label: 'com.example.job',
+  programArguments: ['/usr/local/bin/job'],
+};
+
+const host = (euid = 0, privileged = false) =>
+  fakeRunner({
+    dirs: { '/Library/LaunchDaemons': 0, '/Users/someone/Library/LaunchAgents': 501 },
+    euid,
+    privileged,
+    users: { someone: { gid: 20, home: '/Users/someone', uid: 501 } },
+  });
+
+/** `bootstrap`, `write`, … — the verbs, in order, skipping the read-only ones. */
+const writes = (calls: string[][]) =>
+  calls
+    .map((call) => (call[0] === 'write' ? 'write' : call[1]))
+    .filter((verb) => verb !== 'print' && verb !== 'print-disabled');
+
+describe('create', () => {
+  test('writes the plist root:wheel 0644, then bootstraps it', async () => {
+    const fake = host();
+    const attrs = await reconcileJob(fake.runner, job, undefined);
+    expect(writes(fake.calls)).toEqual(['write', 'bootstrap']);
+    expect(fake.files.get(DAEMON)).toMatchObject({ gid: 0, mode: 0o644, uid: 0 });
+    expect(attrs).toMatchObject({
+      loaded: true,
+      plistPath: DAEMON,
+      serviceTarget: 'system/com.example.job',
+      state: 'running',
+    });
+    expect(attrs.plistSha256).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("an agent is written as its user into that user's LaunchAgents", async () => {
+    const fake = host(501);
+    const attrs = await reconcileJob(fake.runner, { ...job, domain: 'gui/501' }, undefined);
+    expect(attrs.plistPath).toBe(AGENT);
+    expect(fake.files.get(AGENT)).toMatchObject({ mode: 0o644, uid: 501 });
+    expect(fake.loaded.has('gui/501/com.example.job')).toBe(true);
+  });
+});
+
+describe('diff', () => {
+  test('noop when nothing changed, on disk or in launchd', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    expect(await diffJob(fake.runner, job, output)).toEqual({ action: 'noop' });
+  });
+
+  test('update when a prop changes the rendered plist', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    expect(await diffJob(fake.runner, { ...job, runAtLoad: true }, output)).toEqual({
+      action: 'update',
+    });
+  });
+
+  test('update when the file was hand-edited, or the job was unloaded behind our back', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    const entry = fake.files.get(DAEMON);
+    if (entry === undefined) throw new Error('no plist');
+    fake.files.set(DAEMON, { ...entry, bytes: new TextEncoder().encode('hand edit') });
+    expect(await diffJob(fake.runner, job, output)).toEqual({ action: 'update' });
+    await reconcileJob(fake.runner, job, output);
+    fake.loaded.clear();
+    expect(await diffJob(fake.runner, job, output)).toEqual({ action: 'update' });
+  });
+
+  test('replace, deleting first, only when label or domain changes', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    const replace = { action: 'replace', deleteFirst: true } as const;
+    expect(await diffJob(fake.runner, { ...job, label: 'com.example.renamed' }, output)).toEqual(
+      replace,
+    );
+    expect(await diffJob(fake.runner, { ...job, domain: 'gui/501' }, output)).toEqual(replace);
+  });
+
+  test('a bad declaration fails the plan, not the apply', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    await expect(diffJob(fake.runner, { ...job, startInterval: 0 }, output)).rejects.toThrow(
+      'startInterval',
+    );
+  });
+});
+
+describe('update', () => {
+  test('write, then bootout, then bootstrap — a restart with a new pid', async () => {
+    const fake = host();
+    const first = await reconcileJob(fake.runner, job, undefined);
+    fake.calls.length = 0;
+    fake.state.lingerPrints = 2;
+    const second = await reconcileJob(fake.runner, { ...job, runAtLoad: true }, first);
+    expect(writes(fake.calls)).toEqual(['write', 'bootout', 'bootstrap']);
+    expect(second.pid).not.toBe(first.pid);
+    expect(second.plistSha256).not.toBe(first.plistSha256);
+  });
+
+  test('a converged job is not restarted', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.calls.length = 0;
+    const again = await reconcileJob(fake.runner, job, output);
+    expect(writes(fake.calls)).toEqual([]);
+    expect(again.pid).toBe(output.pid);
+  });
+
+  test('a failed bootstrap leaves state behind, so the next diff retries', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.state.bootstrapFailure = {
+      exitCode: 5,
+      stderr: 'Bootstrap failed: 5: Input/output error',
+      stdout: '',
+    };
+    const changed = { ...job, runAtLoad: true };
+    await expect(reconcileJob(fake.runner, changed, output)).rejects.toThrow('NOT RUNNING');
+    expect(fake.loaded.size).toBe(0);
+    expect(await diffJob(fake.runner, changed, output)).toEqual({ action: 'update' });
+  });
+});
+
+describe('refusals', () => {
+  test('the system domain as a non-root user: refused before anything is written', async () => {
+    const fake = host(501);
+    await expect(reconcileJob(fake.runner, job, undefined)).rejects.toThrow('never calls sudo');
+    expect(writes(fake.calls)).toEqual([]);
+    expect(fake.calls).toEqual([]);
+  });
+
+  test('a runner that declares itself privileged may write the system domain', async () => {
+    const fake = host(501, true);
+    expect((await reconcileJob(fake.runner, job, undefined)).loaded).toBe(true);
+  });
+
+  test("another user's gui domain needs root", async () => {
+    const fake = fakeRunner({
+      euid: 501,
+      users: { other: { gid: 20, home: '/Users/other', uid: 502 } },
+    });
+    await expect(
+      reconcileJob(fake.runner, { ...job, domain: 'gui/502' }, undefined),
+    ).rejects.toThrow('another user');
+  });
+
+  test('a gui uid with no user on the host', async () => {
+    const fake = host();
+    await expect(
+      reconcileJob(fake.runner, { ...job, domain: 'gui/777' }, undefined),
+    ).rejects.toThrow('no home');
+  });
+
+  test('a disabled label is left disabled, with the command to change that', async () => {
+    const fake = host();
+    fake.disabled.add('system/com.example.job');
+    await expect(reconcileJob(fake.runner, job, undefined)).rejects.toThrow(
+      'launchctl enable system/com.example.job',
+    );
+    expect(fake.files.has(DAEMON)).toBe(false);
+  });
+
+  test('a reserved label never reaches the host', async () => {
+    const fake = host();
+    await expect(
+      reconcileJob(fake.runner, { ...job, label: 'org.nixos.job' }, undefined),
+    ).rejects.toThrow('another tool owns');
+    expect(fake.calls).toEqual([]);
+  });
+});
+
+describe('read', () => {
+  test('nothing on disk and nothing loaded is undefined', async () => {
+    expect(await readJob(host().runner, job)).toBeUndefined();
+  });
+
+  test('a plist on disk that is not loaded reads as present, not loaded', async () => {
+    const fake = host();
+    await reconcileJob(fake.runner, job, undefined);
+    fake.loaded.clear();
+    expect(await readJob(fake.runner, job)).toMatchObject({ loaded: false, plistPath: DAEMON });
+  });
+});
+
+describe('delete', () => {
+  test('boots out, removes the plist, and is idempotent', async () => {
+    const fake = host();
+    const output = await reconcileJob(fake.runner, job, undefined);
+    fake.calls.length = 0;
+    await deleteJob(fake.runner, output);
+    expect(writes(fake.calls)).toEqual(['bootout']);
+    expect(fake.files.has(DAEMON)).toBe(false);
+    expect(fake.loaded.size).toBe(0);
+    await deleteJob(fake.runner, output);
+  });
+
+  test('refused for a non-root user in the system domain', async () => {
+    const root = host();
+    const output = await reconcileJob(root.runner, job, undefined);
+    await expect(deleteJob(host(501).runner, output)).rejects.toThrow('needs root');
+  });
+});

package/src/launchd/job-lifecycle.ts

@@ -0,0 +1,194 @@
+/**
+ * LaunchdJob's read / diff / reconcile / delete as plain async functions over a HostRunner — split
+ * from job.ts so the whole lifecycle runs against fake-runner.ts in tests, with no real launchd.
+ * The checks made before any write live in job-preflight.ts.
+ *
+ * ★ THE ORDER IS WRITE, BOOTOUT, BOOTSTRAP — not bootout first. launchd reads the plist only at
+ *   bootstrap, so writing the new file while the old job runs changes nothing yet, and a write that
+ *   fails (disk full, EACCES) leaves the old job running instead of leaving nothing running.
+ * ⚠️ A FAILED BOOTSTRAP LEAVES THE JOB DOWN. On an UPDATE the new plist stays on disk, the state
+ *   keeps the previous digest, and the next deploy retries. On a CREATE the plist this deploy wrote
+ *   is removed again: left behind, the next plan's recovery `read` would find a plist with no
+ *   state and report it `Unowned`, and every later deploy would demand `--adopt` for our own file.
+ *   There is no rollback to an older plist: one that launchd refuses is a declaration to fix, and
+ *   re-bootstrapping the old one could fail for the same host-side reason.
+ */
+import type { Diff } from 'alchemy/Diff';
+import {
+  type LaunchdJobAttributes,
+  type LaunchdJobProps,
+  parseDomain,
+  renderJob,
+  sha256Hex,
+} from './job-form.ts';
+import {
+  type Identity,
+  type Location,
+  assertMayWrite,
+  assertReplaceable,
+  assertUnclaimed,
+  assertValid,
+  locate,
+  preflight,
+  refuse,
+} from './job-preflight.ts';
+import { type ServiceStatus, bootoutIfLoaded, bootstrap, printService } from './launchctl.ts';
+import type { HostRunner } from './runner.ts';
+
+const attributesOf = (
+  props: Identity,
+  location: Location,
+  plistSha256: string,
+  status: ServiceStatus,
+): LaunchdJobAttributes => ({
+  domain: props.domain,
+  label: props.label,
+  loaded: status.loaded,
+  plistPath: location.plistPath,
+  plistSha256,
+  serviceTarget: location.target,
+  ...(status.state === undefined ? {} : { state: status.state }),
+  ...(status.pid === undefined ? {} : { pid: status.pid }),
+  ...(status.lastExitCode === undefined ? {} : { lastExitCode: status.lastExitCode }),
+});
+
+/** What is on the host now: the plist's digest and launchd's view. `undefined` when neither exists. */
+export const readJob = async (
+  runner: HostRunner,
+  props: Identity,
+): Promise<LaunchdJobAttributes | undefined> => {
+  const location = await locate(runner, props);
+  const bytes = await runner.readFile(location.plistPath);
+  const status = await printService(runner, location.target);
+  if (bytes === undefined && !status.loaded) return undefined;
+  return attributesOf(props, location, bytes === undefined ? '' : sha256Hex(bytes), status);
+};
+
+/**
+ * ★ `deleteFirst`: labels are unique per domain, and the old and new job would otherwise run the
+ *   same program side by side — same port, same files — until the old one is deleted. A brief
+ *   outage beats two copies. ⛔ Which is why everything the new job's reconcile would refuse is
+ *   refused HERE, at plan time (job-preflight.ts): after the delete it would be too late.
+ * `full` is the whole declaration when resolved; job.ts passes only the identity otherwise.
+ */
+export const replaceDiff = async (
+  runner: HostRunner,
+  next: Identity,
+  full: LaunchdJobProps | undefined,
+  output: LaunchdJobAttributes,
+): Promise<Diff> => {
+  // ★ Validate before rendering, so a bad declaration shows its whole list, not a render error.
+  if (full !== undefined) assertValid(full);
+  const rendered = full === undefined ? undefined : renderJob(full).sha256;
+  await assertReplaceable(runner, next, full, output, rendered);
+  return { action: 'replace', deleteFirst: true };
+};
+
+export const diffJob = async (
+  runner: HostRunner,
+  news: LaunchdJobProps,
+  output: LaunchdJobAttributes,
+): Promise<Diff> => {
+  if (news.label !== output.label || news.domain !== output.domain) {
+    return replaceDiff(runner, news, news, output);
+  }
+  assertValid(news);
+  const desired = renderJob(news).sha256;
+  // ⛔ BOTH digests: the stored one catches a bootstrap that failed after the write landed, the live
+  //   one catches a hand edit. Either alone would report `noop` over a job that is not what we say.
+  if (desired !== output.plistSha256) return { action: 'update' };
+  const live = await readJob(runner, news);
+  if (live === undefined || !live.loaded || live.plistSha256 !== desired)
+    return { action: 'update' };
+  return { action: 'noop' };
+};
+
+export const reconcileJob = async (
+  runner: HostRunner,
+  props: LaunchdJobProps,
+  output: LaunchdJobAttributes | undefined,
+): Promise<LaunchdJobAttributes> => {
+  assertValid(props);
+  const { location, status } = await preflight(runner, props);
+  const rendered = renderJob(props);
+  /**
+   * ⚠️ AN `output` UNDER ANOTHER LABEL OR DOMAIN means the engine planned an UPDATE across a rename —
+   *   which it does whenever diff could not see the rename (a label that was itself an unresolved
+   *   Output at plan time; job.ts). Bootstrapping the new label alone would orphan the old job,
+   *   still running, with nothing left in state to ever remove it. So do what the replace would
+   *   have done: every check above first, then delete the old job, then create the new one.
+   */
+  const renamed =
+    output !== undefined && (output.label !== props.label || output.domain !== props.domain);
+  const prior = renamed ? undefined : output;
+  // ⛔ No prior state for THIS identity: whatever is there already belongs to someone else.
+  if (prior === undefined) {
+    await assertUnclaimed(runner, props.label, location, status, rendered.sha256);
+  }
+  if (renamed) await deleteJob(runner, output);
+  const before = await runner.readFile(location.plistPath);
+  // ★ Already converged (a retried deploy, or an adopted job that matches): do not restart it.
+  // ⛔ The STORED digest is part of the test: a write that landed before a failed bootout leaves
+  //   the new plist on disk and the OLD job loaded — both look right, and only state knows better.
+  if (
+    status.loaded &&
+    before !== undefined &&
+    sha256Hex(before) === rendered.sha256 &&
+    prior?.plistSha256 === rendered.sha256
+  ) {
+    return attributesOf(props, location, rendered.sha256, status);
+  }
+  /**
+   * ⚠️ launchd refuses a daemon plist that is not root:wheel or is group/world-writable ("bad
+   *   ownership/permissions"), so the system domain always writes 0644 root:wheel. An agent's plist
+   *   belongs to its user. REASONED from launchd's documented behaviour, not measured here (no
+   *   bootstrap was run to write this); the nix-darwin daemons on the reference host are 0644 root.
+   */
+  await runner.writeFileAtomic(
+    location.plistPath,
+    rendered.bytes,
+    location.domain.kind === 'system'
+      ? { gid: 0, mode: 0o644, uid: 0 }
+      : { mode: 0o644, uid: location.domain.uid },
+  );
+  await bootoutIfLoaded(runner, location.target);
+  const failed = async (detail: string): Promise<never> => {
+    // ⚠️ A failed removal must not replace the bootstrap error, nor let the message claim it worked.
+    const removed =
+      before === undefined &&
+      (await runner.removeFile(location.plistPath).then(
+        () => true,
+        () => false,
+      ));
+    throw refuse(
+      props.label,
+      removed
+        ? `bootstrap failed, so the job is NOT RUNNING; the plist this deploy wrote was removed ` +
+            `again, so the next deploy starts clean. ${detail}`
+        : `bootstrap failed, so the job is NOT RUNNING; the new plist is at ${location.plistPath} ` +
+            `and the next deploy retries. ${detail}`,
+    );
+  };
+  try {
+    await bootstrap(runner, props.domain, location.plistPath);
+  } catch (cause) {
+    return failed(cause instanceof Error ? cause.message : String(cause));
+  }
+  const after = await printService(runner, location.target);
+  if (!after.loaded) return failed('bootstrap exited 0 but launchctl print cannot find the job');
+  return attributesOf(props, location, rendered.sha256, after);
+};
+
+/** Boot out, then remove the plist. Idempotent: an absent job and an absent file are success. */
+export const deleteJob = async (
+  runner: HostRunner,
+  output: LaunchdJobAttributes,
+): Promise<void> => {
+  const domain = parseDomain(output.domain);
+  if (domain === undefined) throw refuse(output.label, `unknown domain ${output.domain}`);
+  assertMayWrite(runner, output.label, domain);
+  // ★ A gui domain with no login session reads as "not loaded" (launchctl.ts), so the plist is
+  //   still removed — which is what stops launchd loading it again at that user's next login.
+  await bootoutIfLoaded(runner, output.serviceTarget);
+  await runner.removeFile(output.plistPath);
+};