@homeflare/alchemy 0.25.0 → 0.26.0

package/src/linux/unit-activating.test.ts

@@ -0,0 +1,164 @@
+/**
+ * `started: false` against a unit that is `ActiveState=activating` — the timer-driven `Type=oneshot`
+ * scenario `isUnitRunning` (unit-form.ts) exists for, and the crash-restart (`auto-restart`)
+ * `SubState` that scenario must not be confused with. Split from unit-lifecycle.test.ts to stay
+ * under this file's line cap; see that file for the rest of the family's behaviour.
+ *
+ * ⛔ THE BUG THIS GUARDS: before `isUnitRunning`, `diffUnit` read `ActiveState=activating` on a
+ *   `started: false` unit as drift and planned `update`; `settle` then called `systemctl stop` on a
+ *   check that was already running, mid-run, driven by its own `.timer`. A redeploy must plan to
+ *   nothing while the run is in progress — these tests are that redeploy.
+ * ⛔ THE SECOND BUG THAT ALMOST SHIPPED WITH THE FIRST FIX: an `activating` unit whose `SubState`
+ *   is `auto-restart` (or `auto-restart-queued`) is systemd's crash-restart backoff, not a start —
+ *   see isUnitRunning's own comment. A `started: false` unit that is crash-looping must still be
+ *   stopped; the "auto-restart backoff is still drift" test below is that case.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { type SystemdUnitProps, isUnitRunning, renderUnit } from './unit-form.ts';
+import { diffUnit, readUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+const NAME = 'hf-node-check.service';
+const PATH = `/etc/systemd/system/${NAME}`;
+/** ⛔ No `[Install]`: a timer-driven oneshot is `enabled: false` — its `.timer` starts it, not `systemctl enable`. */
+const content = renderUnit([
+  { lines: [['Description', 'a PVE node check']], name: 'Unit' },
+  {
+    lines: [
+      ['Type', 'oneshot'],
+      ['ExecStart', '/usr/bin/check-node'],
+    ],
+    name: 'Service',
+  },
+]);
+const props: SystemdUnitProps = { content, enabled: false, name: NAME, started: false };
+const host = () => fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+const verbs = (calls: string[][]) =>
+  calls.filter((call) => call[0] === 'systemctl').map((call) => call[1]);
+
+/** `readUnit` narrowed to defined, so callers can pass it straight to diffUnit/reconcileUnit. */
+const outputFor = async (fake: ReturnType<typeof host>, of: SystemdUnitProps) => {
+  const found = await readUnit(fake.runner, of);
+  if (found === undefined) throw new Error(`${of.name} not found on the fake host`);
+  return found;
+};
+
+describe('isUnitRunning — the one predicate diff and settle share', () => {
+  test('active always counts as running, whatever started declares', () => {
+    expect(isUnitRunning('active', 'running', true)).toBe(true);
+    expect(isUnitRunning('active', 'running', false)).toBe(true);
+  });
+  test('a genuine start counts as running only when started is declared', () => {
+    expect(isUnitRunning('activating', 'start', true)).toBe(true);
+    expect(isUnitRunning('activating', 'start', false)).toBe(false);
+  });
+  // ⛔ Added on adversarial review: `auto-restart`/`auto-restart-queued` are ALSO
+  //   `ActiveState=activating` (systemd's crash-restart backoff, service.c), not a fresh start —
+  //   see isUnitRunning's own comment. Without this, started: false would stop enforcing itself on
+  //   exactly the unit most in need of it: one that is crash-looping.
+  test('auto-restart backoff always counts as running — it is a crash loop, not a fresh start', () => {
+    expect(isUnitRunning('activating', 'auto-restart', false)).toBe(true);
+    expect(isUnitRunning('activating', 'auto-restart-queued', false)).toBe(true);
+  });
+  test('inactive and failed never count as running', () => {
+    expect(isUnitRunning('inactive', 'dead', true)).toBe(false);
+    expect(isUnitRunning('failed', 'failed', false)).toBe(false);
+  });
+});
+
+describe('started: false against a oneshot mid-run', () => {
+  test('activating, everything else converged: diff is noop', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { activeState: 'activating', enabled: false, subState: 'start' });
+    const output = await outputFor(fake, props);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'noop' });
+  });
+
+  test('active is drift: diff is update, and settle stops it', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { active: true, enabled: false });
+    const output = await outputFor(fake, props);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    const settled = await reconcileUnit(fake.runner, props, output);
+    expect(verbs(fake.calls.slice(before))).toContain('stop');
+    expect(settled.active).toBe(false);
+  });
+
+  test('activating during an unrelated unit-file update: settle does not stop it', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { activeState: 'activating', enabled: false, subState: 'start' });
+    const output = await outputFor(fake, props);
+    const changed = { ...props, content: content.replace('check-node', 'check-node-v2') };
+    expect(await diffUnit(fake.runner, changed, output)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    await reconcileUnit(fake.runner, changed, output);
+    expect(verbs(fake.calls.slice(before))).not.toContain('stop');
+  });
+
+  test('failed is not running either: diff is noop', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { activeState: 'failed', enabled: false });
+    const output = await outputFor(fake, props);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'noop' });
+  });
+
+  // ⛔ ADVERSARIAL-REVIEW CASE: `activating` is not only a fresh start. A unit that was started by
+  //   hand and now crash-loops (`Restart=on-failure`) sits in `ActiveState=activating`,
+  //   `SubState=auto-restart` for nearly all of its wall-clock time. The oneshot exemption above
+  //   must NOT swallow this one — started: false has to keep stopping it, same as plain `active`.
+  test('auto-restart backoff is still drift: diff is update, and settle still stops it', async () => {
+    const fake = host();
+    const crashy = renderUnit([
+      { lines: [['Description', 'started by hand, now crash-looping']], name: 'Unit' },
+      {
+        lines: [
+          ['ExecStart', '/usr/bin/flaky'],
+          ['Restart', 'on-failure'],
+          ['RestartSec', '5'],
+        ],
+        name: 'Service',
+      },
+    ]);
+    const crashyProps: SystemdUnitProps = {
+      content: crashy,
+      enabled: false,
+      name: NAME,
+      started: false,
+    };
+    fake.placeUnit(PATH, crashy, {
+      activeState: 'activating',
+      enabled: false,
+      subState: 'auto-restart',
+    });
+    const output = await outputFor(fake, crashyProps);
+    expect(await diffUnit(fake.runner, crashyProps, output)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    const settled = await reconcileUnit(fake.runner, crashyProps, output);
+    expect(verbs(fake.calls.slice(before))).toContain('stop');
+    expect(settled.active).toBe(false);
+  });
+});
+
+describe('started: true (or omitted) keeps counting activating as running', () => {
+  test('no start is issued while the unit is already activating', async () => {
+    const fake = host();
+    const enabledContent = renderUnit([
+      { lines: [['Description', 'a long-running service']], name: 'Unit' },
+      { lines: [['ExecStart', '/usr/bin/thing']], name: 'Service' },
+      { lines: [['WantedBy', 'multi-user.target']], name: 'Install' },
+    ]);
+    const started: SystemdUnitProps = { content: enabledContent, name: NAME };
+    fake.placeUnit(PATH, enabledContent, {
+      activeState: 'activating',
+      enabled: true,
+      subState: 'start',
+    });
+    const output = await outputFor(fake, started);
+    expect(await diffUnit(fake.runner, started, output)).toEqual({ action: 'noop' });
+    const before = fake.calls.length;
+    const settled = await reconcileUnit(fake.runner, started, output);
+    expect(verbs(fake.calls.slice(before))).not.toContain('start');
+    expect(settled.active).toBe(true);
+  });
+});

package/src/linux/unit-form.ts

@@ -90,6 +90,57 @@ export const digestOf = (text: string): string => sha256Hex(new TextEncoder().en
 export const configDigest = (restartOn: readonly string[] | undefined): string =>
   digestOf((restartOn ?? []).join('\n'));
 
+/**
+ * Whether `activeState`/`subState` count as "the unit is running" against a declared `started` —
+ * the ONE place this decision is made, so `diffUnit` (unit-lifecycle.ts) and `settle`
+ * (unit-settle.ts) can never disagree about it.
+ *
+ * ⛔ WHY THIS EXISTS: a `Type=oneshot` service driven by a `.timer` (no `[Install]`, declared
+ *   `started: false, enabled: false` — its timer starts it, not this resource) reports
+ *   `ActiveState=activating` for the run's whole duration, not an instant. Written for the PVE
+ *   node-check unit that first hit this: ~1.2s, every 60s. A plan taken mid-run must not read that
+ *   run as drift, and a deploy must not `systemctl stop` a check that is already in flight.
+ * ★ systemd.service(5) §`Type=`, `oneshot` (man7.org mirror, read 2026-09-23): with no
+ *   `RemainAfterExit=`, the service manager holds the unit `activating` for as long as
+ *   `ExecStart=` runs, then moves it straight to `dead`/`inactive` (or `failed`) — it never passes
+ *   through `active`. So for `started: false`, `activating` is exactly a run in progress, and
+ *   `active` is the one state a oneshot never reaches on its own: that is the drift, and the only
+ *   thing settle stops.
+ * ⛔ CRASH-LOOP GUARD, added on adversarial review: `ActiveState=activating` is not only "starting
+ *   for the first time" — a service with `Restart=` waiting out its `RestartSec=` backoff between
+ *   crash attempts is ALSO `activating`, with `SubState=auto-restart` (or `auto-restart-queued`).
+ *   A unit declared `started: false` that is crash-looping sits there for nearly all of its
+ *   wall-clock time. Without this guard the oneshot exemption above would read that loop as
+ *   converged forever, and a deploy would never again issue the `stop` that ends it — silently
+ *   defeating `started: false` on exactly the unit that most needs it enforced. So only a genuine
+ *   start (`SubState` anything else — `start`, `start-pre`, `start-post`, …) gets the exemption;
+ *   an auto-restart substate counts as running regardless of `started`, same as `active` does.
+ * ★ SOURCE, not measured against a live host: systemd's own `service.c`
+ *   `state_translation_table` (github.com/systemd/systemd, read 2026-09-23) maps both
+ *   `SERVICE_AUTO_RESTART` and `SERVICE_AUTO_RESTART_QUEUED` to `UNIT_ACTIVATING`, and
+ *   `unit-def.c`'s `service_state_table` names their `SubState` strings `"auto-restart"` and
+ *   `"auto-restart-queued"`. ⚠️ REASONED NOT MEASURED: no unit was actually crash-looped and read
+ *   back with `systemctl show` for this change — the systemd source is the citation, unlike
+ *   systemctl.ts's own header, which is a live-host trace.
+ * ⚠️ THE TRADE-OFF THIS ACCEPTS: a `Type=notify` (or other long-running type) unit stuck in a
+ *   genuine `activating`/`start` with `started: false` — never reaching `active` and never
+ *   crash-looping either — reads as converged, not drift, until it reaches `active`. A unit hung
+ *   like that is exactly the case a human should look at, not one this predicate auto-corrects by
+ *   stopping it out from under whatever else depends on it.
+ * ★ `started: true` (the default, when omitted) is unchanged: `active` or `activating` (any
+ *   `subState`) both count as running, so a start already in flight is never started twice.
+ */
+export const isUnitRunning = (
+  activeState: string,
+  subState: string | undefined,
+  started: boolean,
+): boolean => {
+  if (activeState === 'active') return true;
+  if (activeState !== 'activating') return false;
+  if (subState === 'auto-restart' || subState === 'auto-restart-queued') return true;
+  return started;
+};
+
 /** Sections → an INI unit file. ★ Keys and values pass through untouched; see the file header. */
 export const renderUnit = (sections: readonly UnitSection[]): string =>
   `${sections
@@ -104,7 +155,8 @@ export const unitText = (props: SystemdUnitProps): string =>
 export const unitPathFor = (props: SystemdUnitProps): string =>
   `${props.directory ?? DEFAULT_UNIT_DIRECTORY}/${props.name}`;
 
-const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
+/** ★ Exported so sudo-allowlist.ts validates a systemctl unit operand against the same pattern. */
+export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
 /** systemd's own unit types. ★ Fixed vocabulary from `systemd.unit(5)`, not a guess at directives. */
 const TYPES = new Set([
   'automount',

package/src/linux/unit-lifecycle.ts

@@ -27,6 +27,7 @@ import {
   UNIT_WRITE,
   configDigest,
   digestOf,
+  isUnitRunning,
   unitPathFor,
   unitText,
 } from './unit-form.ts';
@@ -75,10 +76,16 @@ export const diffUnit = async (
   const live = await readUnit(runner, news);
   if (live === undefined || live.unitSha256 !== desired) return update();
   if (live.enabled !== (news.enabled !== false)) return update();
-  if (live.active !== (news.started !== false)) return update();
   // ⚠️ systemd's own word for "the file on disk is newer than what I loaded" — a write that landed
-  //   without its reload. It is drift that neither digest can see.
+  //   without its reload. It is drift that neither digest can see. ★ Also the freshest read of
+  //   ActiveState/SubState — not `live.active`, which is a raw "active or activating" reading with
+  //   no SubState in it. Whether the current state counts as drift against `started` is the
+  //   isUnitRunning policy (unit-form.ts), shared with settle so the two can never disagree.
   const status = await showUnit(runner, news.name);
+  const wantStarted = news.started !== false;
+  if (isUnitRunning(status.activeState, status.subState, wantStarted) !== wantStarted) {
+    return update();
+  }
   return status.needDaemonReload ? update() : { action: 'noop' };
 };
 

package/src/linux/unit-settle.ts

@@ -13,6 +13,7 @@ import {
   type SystemdUnitAttributes,
   type SystemdUnitProps,
   configDigest,
+  isUnitRunning,
   unitPathFor,
 } from './unit-form.ts';
 import {
@@ -81,10 +82,13 @@ export const settle = async (
   try {
     if (wantEnabled && (!isEnabled || step.changed)) await enableUnit(runner, props.name);
     if (!wantEnabled && isEnabled) await disableUnit(runner, props.name);
-    const active = step.status.activeState === 'active' || step.status.activeState === 'activating';
+    // ★ isUnitRunning (unit-form.ts): the same started-aware policy diffUnit uses, so a unit this
+    //   deploy never touches — a `started: false` oneshot mid-run — is never stopped here either.
+    //   `subState` is what tells that mid-run apart from a crash-restart backoff, which still stops.
+    const running = isUnitRunning(step.status.activeState, step.status.subState, wantStarted);
     if (!wantStarted) {
-      if (active) await stopUnit(runner, props.name);
-    } else if (!active) await startUnit(runner, props.name);
+      if (running) await stopUnit(runner, props.name);
+    } else if (!running) await startUnit(runner, props.name);
     else if (step.changed || step.configChanged) await restartUnit(runner, props.name);
   } catch (cause) {
     return undo(cause instanceof Error ? cause.message : String(cause));
@@ -96,7 +100,7 @@ export const settle = async (
    *   as drift, in either direction.
    */
   const after = await showUnit(runner, props.name);
-  if (wantStarted && after.activeState !== 'active' && after.activeState !== 'activating') {
+  if (wantStarted && !isUnitRunning(after.activeState, after.subState, wantStarted)) {
     return undo(`systemctl reported success but the unit is ${after.activeState}.`);
   }
   const settled = attributesOf(props, step.desired, after);

package/src/litellm/fake-litellm.ts

@@ -48,6 +48,8 @@ export const startFakeLitellm = (options?: {
     new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
 
   const server = Bun.serve({
+    // ⚠️ Loopback, not the wildcard default — see proxmox/fake-pve-lxc.ts for the race.
+    hostname: '127.0.0.1',
     port: 0,
     fetch: async (req) => {
       const url = new URL(req.url);

package/src/proxmox/client.test.ts

@@ -12,7 +12,11 @@ import { PveError, pveWith } from './client.ts';
 import type { PveCredential, PveTarget } from './credentials.ts';
 import { orderedMembers, resetLastGoodForTest } from './members.ts';
 
-type ServeOptions = { fetch(request: Request): Response | Promise<Response>; port: number };
+type ServeOptions = {
+  fetch(request: Request): Response | Promise<Response>;
+  hostname: string;
+  port: number;
+};
 const { Bun } = globalThis as unknown as {
   Bun: { serve(options: ServeOptions): { port: number; stop(closeActive: boolean): void } };
 };
@@ -84,6 +88,8 @@ const counting = (data: unknown) => {
       hits += 1;
       return Response.json({ data });
     },
+    // ⚠️ Loopback, not the wildcard default — see fake-pve-lxc.ts for the measured race.
+    hostname: '127.0.0.1',
     port: 0,
   });
   return { hits: () => hits, port: server.port, stop: () => server.stop(true) };
@@ -106,7 +112,11 @@ describe('cluster member failover', () => {
 
   it('does not fail over on HTTP 500 from the first member', async () => {
     resetLastGoodForTest();
-    const bad = Bun.serve({ fetch: () => new Response('fail', { status: 500 }), port: 0 });
+    const bad = Bun.serve({
+      fetch: () => new Response('fail', { status: 500 }),
+      hostname: '127.0.0.1',
+      port: 0,
+    });
     const good = counting([]);
     try {
       const error = await run(pveWith(target([A, B]), CRED, 'GET', 'pools').pipe(Effect.flip), {
@@ -144,7 +154,11 @@ describe('cluster member failover', () => {
 
   it('does not re-send a write after a transport timeout', async () => {
     resetLastGoodForTest();
-    const hang = Bun.serve({ fetch: () => new Promise<Response>(() => {}), port: 0 });
+    const hang = Bun.serve({
+      fetch: () => new Promise<Response>(() => {}),
+      hostname: '127.0.0.1',
+      port: 0,
+    });
     const backup = counting('UPID:1');
     try {
       await run(

package/src/proxmox/fake-pve-lxc.ts

@@ -185,7 +185,16 @@ export const fakePve = (): FakePve => {
     return json({ data: null, message: 'unhandled\n' }, 501);
   };
 
-  const server = Bun.serve({ fetch: handle, port: 0 });
+  // 🔴 LOOPBACK, NOT THE DEFAULT WILDCARD — AND THAT WAS THE FLAKE. Measured 2026-09-23 on
+  //   macOS: `Bun.serve({ port: 0 })` binds 0.0.0.0, and the kernel will hand a wildcard
+  //   port-0 bind a port some OTHER socket already holds on 127.0.0.1 (16,373 binds in, it
+  //   did). Loopback traffic then goes to the more specific listener, so this fake's own
+  //   requests reached another process's server — another test suite's fake, when several
+  //   agents run `bun test` at once — and a plan failed with "Transport error" on a GET to a
+  //   server that was up. A 127.0.0.1 port-0 bind is never handed a port in use on
+  //   127.0.0.1, and nothing more specific can shadow it. tests/loopback-servers.test.ts
+  //   keeps every test server this way.
+  const server = Bun.serve({ fetch: handle, hostname: '127.0.0.1', port: 0 });
   const port = String(server.port);
   const remapped = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
     const url = new URL(input instanceof Request ? input.url : String(input));