@homeflare/alchemy 0.40.0 → 0.41.0

package/docs/talos-argocd-dogfood.md

@@ -0,0 +1,160 @@
+# Talos + Argo CD dogfood — Distilled and Alchemy path
+
+Status: decision record — fixes the per-vendor Distilled/Alchemy path for the
+Talos + Argo CD dogfood stack; retire when the stack ships and each row is
+proven live.
+Verified: 2026-09-27 (LAND pass: CRD ownership, Talos K-A3, Cilium CNI
+ordering, topology and the interim-package rule checked against merged PRs
+262/295/307/311; see each section below).
+
+Opened 2026-09-24 after
+[PR 242](https://github.com/taslabs-net/homeflare-kit/pull/242) closed without
+merge.
+
+Placeholder stack: Talos Kubernetes on Proxmox VE, **Argo CD owns GitOps**.
+This page is the Distilled / Alchemy path for each vendor — not a stack file,
+and not a licence to invent SDKs.
+
+## Why there are no interim packages
+
+[distilled-interim.md](./distilled-interim.md) is generate+copy from a real
+vendor schema (distilled clone Steps 1–8, then copy `src/` into
+`packages/distilled-<vendor>`). ⛔ **`src/` is copied, never hand-written.**
+A stub invented so a `@distilled.cloud/<vendor>` name can publish is the
+failure #242 shipped: Alchemy would `catchTag` errors from a client nobody
+can regenerate. ⛔ Do not add npm aliases for packages that do not exist.
+
+## Per-vendor decision
+
+| vendor    | decision                                                                                                                                                                                                                                                                                                |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Headlamp  | Skip Distilled / Alchemy vendor family — Argo Application / Helm                                                                                                                                                                                                                                        |
+| Traefik   | No Distilled SDK (no official OpenAPI; do not invent)                                                                                                                                                                                                                                                   |
+| Cilium    | No hand-written interim — install vehicle is D-S2 (open); CRDs via upstream Alchemy `Kubernetes.Manifest`                                                                                                                                                                                               |
+| CNPG      | `postgresql.cnpg.io/v1` CRDs — upstream Alchemy `Kubernetes.Manifest` (S1), not `@distilled.cloud/kubernetes` (built-in API groups only)                                                                                                                                                                |
+| Valkey    | operator CRDs — upstream Alchemy `Kubernetes.Manifest` (S1); Sentinel is RESP, not HTTP                                                                                                                                                                                                                 |
+| Argo CD   | `Application`/`AppProject`/`ApplicationSet` — upstream Alchemy `Kubernetes.Manifest` (decision 49); `Repository`/`RepoCreds`/`Cluster` — `Argocd.Repository`/`RepoCreds`/`Cluster` (kit, built over `@distilled.cloud/argocd`, [PR 262](https://github.com/taslabs-net/homeflare-kit/pull/262), merged) |
+| Talos CLI | No Distilled Talos SDK — stays on `talosctl`, reworked under K-A3 ([PR 307](https://github.com/taslabs-net/homeflare-kit/pull/307)/[311](https://github.com/taslabs-net/homeflare-kit/pull/311): `insecure` prop dropped, `Bootstrap.peers` added)                                                      |
+
+Headlamp's `/config` and cluster proxy are not a vendor control plane.
+
+Traefik declarative config is Kubernetes CRDs (`IngressRoute`, `Middleware`, …
+— `traefik.io`, not a built-in group) / Helm values (experimental flags as
+Helm props). CRDs go through upstream Alchemy `Kubernetes.Manifest` (S1), the
+same as every other vendor's CRDs on this page, never
+`@distilled.cloud/kubernetes`. The dashboard `GET /api/…` is read-only
+runtime — optional later, not the dogfood install path.
+
+Cilium's BGP and network-policy objects are genuine CRDs, not a built-in
+Kubernetes API group, so they go through upstream Alchemy's
+`Kubernetes.Manifest` (S1) — never `@distilled.cloud/kubernetes`: its 24
+service files (checked at the kit's pin, `c2a78002`) cover only built-in
+apiserver groups, and its `apiextensions` service defines CRD _schemas_, not
+CRD _instances_. The install vehicle itself — inline manifests in the seeded
+Talos machine config vs. a Helm step between `Kubeconfig` and `ClusterHealth`
+— is **D-S2, still open**
+([first-boot doc](https://github.com/taslabs-net/homeflare-kit/blob/main/docs/plans/2026-09-26-talos-stack-first-boot.md#tim-must-decide),
+"Tim must decide"; inline manifests is the doc's recommendation, not yet
+accepted). Either vehicle must set `cluster.network.cni.name: none` and
+`cluster.proxy.disabled: true` (kube-proxy replacement) in the seeded config,
+because Argo CD cannot install Cilium — Argo CD itself needs pod networking
+first. Official swagger exists (`cilium/cilium` `api/v1/openapi.yaml`) but
+the default transport is the unix socket `/var/run/cilium/cilium.sock`;
+generate+copy a Distilled SDK later only if node-local agent health over
+that socket is needed.
+
+Argo CD's own storage — `Repository`, `RepoCreds` and `Cluster` — is a `Secret`
+labeled with Argo CD's own convention, not a published Kubernetes API type, so
+the kit's `Argocd.Repository`/`RepoCreds`/`Cluster` (built over
+`@distilled.cloud/argocd`, already on npm) are the correct owner
+([PR 262](https://github.com/taslabs-net/homeflare-kit/pull/262), merged). The
+objects Argo CD reconciles — `Application`, `AppProject`, `ApplicationSet` —
+are genuine `argoproj.io/v1alpha1` CRDs, so upstream Alchemy's
+`Kubernetes.Manifest` owns those (decision 49, "upstream wins"), not a house
+wrapper — see [argocd.md](./argocd.md) and
+[argocd-kubernetes.md](./argocd-kubernetes.md). No Distilled Talos API in this
+path.
+
+## Gates
+
+- ⛔ Do not publish an interim Distilled package until generate+copy from a
+  real vendor schema ([distilled-interim.md](./distilled-interim.md) steps 1–2).
+- ⛔ Do not invent a Traefik Distilled SDK without an official schema.
+- `Argocd.Repository`/`RepoCreds`/`Cluster` were built ahead of a live
+  Talos-on-PVE cluster ([PR 262](https://github.com/taslabs-net/homeflare-kit/pull/262),
+  merged 2026-09-24; tested against `fake-argocd.ts`, a fake in-memory Argo CD
+  API — the HTTP client and Distilled protocol underneath it are real, only
+  the Argo CD server is faked; never exercised against a real instance) —
+  Tim's build-ahead-of-need call. Declaring and applying
+  `Application`/`AppProject`/`ApplicationSet` objects in a real stack still
+  waits on that cluster existing.
+- Prefer upstream Alchemy Kubernetes resources when they exist (S1).
+
+## Placeholder variables
+
+Names a consuming stack substitutes. Origins use RFC 2606 `*.example.com`.
+Addresses use RFC 5737 documentation ranges. Secret _values_ never appear —
+only env-var NAMES (S25). Nothing here is applied.
+
+### Topology — 3 control plane, no workers today
+
+`homeflare-proxmox`'s `src/talos-shape.ts` declares exactly 3 control-plane
+VMs (`n2`/`n3`/`n4`, vmids 10000–10002) and no worker pool. The
+`TALOS_WORKER_*` rows are placeholders for if/when a worker pool is added;
+nothing consumes them yet.
+
+| variable                              | placeholder                     |
+| ------------------------------------- | ------------------------------- |
+| `TALOS_CLUSTER_NAME`                  | `dogfood`                       |
+| `TALOS_CP_NODES`                      | `cp-a`, `cp-b`, `cp-c`          |
+| `TALOS_WORKER_NODES` (none today)     | `wk-a`, `wk-b`, `wk-c`          |
+| `TALOS_CP_ADDRESSES`                  | `192.0.2.10/24` … `.12`         |
+| `TALOS_WORKER_ADDRESSES` (none today) | `192.0.2.20/24` … `.22`         |
+| `TALOS_CONTROL_PLANE_ENDPOINT`        | `https://k8s.example.com:6443`  |
+| `TALOS_VERSION`                       | `v1.13.x` (never measured live) |
+| `STORAGE_CLASS`                       | `STORAGE_CLASS`                 |
+| `STORAGE_SIZE`                        | `STORAGE_SIZE`                  |
+
+### Cilium BGP
+
+| variable                  | placeholder       |
+| ------------------------- | ----------------- |
+| `CILIUM_BGP_CLUSTER_ASN`  | `64512` (private) |
+| `CILIUM_BGP_PEER_ASN`     | `64513`           |
+| `CILIUM_BGP_PEER_ADDRESS` | `198.51.100.1`    |
+| `CILIUM_BGP_VIP_CIDR`     | `203.0.113.0/24`  |
+
+### Traefik
+
+| variable                     | placeholder                                     |
+| ---------------------------- | ----------------------------------------------- |
+| `TRAEFIK_ENTRYPOINTS`        | `web`, `websecure`                              |
+| `TRAEFIK_EXPERIMENTAL_FLAGS` | Helm props, e.g. `kubernetesGateway`, `knative` |
+| `TRAEFIK_NAMESPACE`          | `traefik`                                       |
+
+### Installs Argo owns
+
+| variable                    | placeholder                  |
+| --------------------------- | ---------------------------- |
+| `HEADLAMP_INGRESS_HOST`     | `headlamp.example.com`       |
+| `CNPG_CLUSTER_NAME`         | `dogfood-pg`                 |
+| `CNPG_INSTANCES`            | `3`                          |
+| `CNPG_SUPERUSER_SECRET_ENV` | `CNPG_SUPERUSER_PASSWORD`    |
+| `VALKEY_SENTINEL_NAME`      | `dogfood-valkey`             |
+| `VALKEY_PASSWORD_ENV`       | `VALKEY_PASSWORD`            |
+| `ARGOCD_SERVER`             | `https://argocd.example.com` |
+| `ARGOCD_TOKEN_ENV`          | `ARGOCD_TOKEN`               |
+
+## Non-goals
+
+- No Flux. Argo CD is the GitOps controller.
+- No new Distilled Talos SDK from this page — `@homeflare/alchemy/talos`
+  already reworked under K-A3 ([PR 307](https://github.com/taslabs-net/homeflare-kit/pull/307),
+  [PR 311](https://github.com/taslabs-net/homeflare-kit/pull/311)); it stays on
+  `talosctl`.
+- No new Alchemy provider code from this page itself — `Argocd.*` (PR 262)
+  and upstream `Kubernetes.Manifest` already cover this stack's objects.
+  Declaring and applying them against a real cluster still waits on
+  Talos-on-PVE existing (see Gates).
+- No `packages/distilled-traefik`, `packages/distilled-cilium`, or other
+  interim Distilled packages for this stack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -131,7 +131,7 @@
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/openbao": "npm:@homeflare/distilled-openbao@0.2.2",
-    "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
+    "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.3.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.3",
     "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.1",

package/src/launchd/fake-runner.ts

@@ -156,6 +156,8 @@ export const fakeRunner = (options: FakeOptions = {}) => {
     lookupUser: async (nameOrId) =>
       options.users?.[nameOrId] ??
       Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    // ★ This fake models launchd, which only ever exists on a Mac — fixed, not an option.
+    platform: 'darwin',
     privileged,
     readFile: async (path) => files.get(path)?.bytes,
     removeFile: async (path) => {

package/src/launchd/index.ts

@@ -24,7 +24,14 @@ export { PlistError, renderPlist } from './plist.ts';
 export type { PortClaim } from './port-claims.ts';
 export { PortRefused, claimPorts, portClaimProblems } from './port-claims.ts';
 export { launchdProviders } from './providers.ts';
-export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
+export type {
+  ExecResult,
+  FileStat,
+  HostPlatform,
+  HostRunner,
+  HostUser,
+  WriteOptions,
+} from './runner.ts';
 export { HostRunnerService, canActAsRoot, hostRunnerLayer } from './runner.ts';
 export type { SudoRunnerOptions } from './sudo-runner.ts';
 export { SudoRefusedError, sudoRunner } from './sudo-runner.ts';

package/src/launchd/local-runner.ts

@@ -15,7 +15,7 @@ import { randomBytes } from 'node:crypto';
 import { lstat, open, readFile, rename, unlink } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { groupQuery, parseGroup, parseUser, userQuery } from './host-lookup.ts';
-import type { ExecResult, FileStat, HostRunner, WriteOptions } from './runner.ts';
+import type { ExecResult, FileStat, HostPlatform, HostRunner, WriteOptions } from './runner.ts';
 
 export type LocalRunnerOptions = {
   /** Kill a spawned program after this long. @default 120_000 */
@@ -98,6 +98,20 @@ const writeAtomic = async (path: string, bytes: Uint8Array, options: WriteOption
 export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
   const timeoutMs = options.execTimeoutMs ?? 120_000;
   const platform = process.platform;
+  // ★ THE ONE PLACE `process.platform` MAY DECIDE HOST BEHAVIOUR: here, the target IS this
+  //   process's own machine, so `process.platform` and `HostRunner.platform` name the same host.
+  //   Everywhere else (chmodChownEnd, host-lookup's callers over ssh) reads `runner.platform`
+  //   instead — see the incident on `HostRunner.platform`'s own doc comment.
+  // ⛔ DECLARED, NEVER GUESSED, past these two: silently folding freebsd/win32/etc. into 'linux'
+  //   would hand a BSD host GNU's `--`, which macOS's own (BSD-flavoured) chmod/chown already
+  //   reject — the same shape of bug this PR fixes. sshRunner's own `uname -s` probe refuses a
+  //   non-Linux target the same way; localRunner refuses here instead of guessing.
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new Error(
+      `localRunner(): unsupported process.platform ${JSON.stringify(platform)} — HostRunner only targets darwin and linux.`,
+    );
+  }
+  const hostPlatform: HostPlatform = platform;
   return {
     effectiveUid: () => process.geteuid?.() ?? -1,
     exec: (argv) => run(argv, timeoutMs),
@@ -109,6 +123,7 @@ export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
       const result = await run(userQuery(platform, nameOrId), timeoutMs);
       return result.exitCode === 0 ? parseUser(platform, result.stdout) : undefined;
     },
+    platform: hostPlatform,
     privileged: false,
     readFile: async (path) => {
       try {

package/src/launchd/runner.ts

@@ -59,7 +59,29 @@ export type WriteOptions = {
 
 export type HostUser = { readonly uid: number; readonly gid: number; readonly home: string };
 
+/**
+ * The two host families a HostRunner ever actually targets. ★ Not `NodeJS.Platform`: nothing
+ *   here runs against `win32`/`aix`/etc, and a narrower type is what makes `runner.platform ===
+ *   'darwin'` exhaustive rather than a string comparison that silently matches nothing.
+ */
+export type HostPlatform = 'darwin' | 'linux';
+
 export interface HostRunner {
+  /**
+   * ⛔ DECLARED, NEVER INFERRED — same rule as `privileged`, and the same failure mode. The OS of
+   *   the TARGET this runner writes to, never of the process running Alchemy: `localRunner()` may
+   *   run ON either, but `sshRunner()`/`sshSudoRunner()` always reach a Linux host from wherever
+   *   Alchemy itself happens to run.
+   * 🔴 INCIDENT, homeflare-ct100 2026-09-27: `Host.Directory`'s chmod/chown end-of-options token
+   *   (directory-lifecycle.ts `chmodChownEnd`) read `process.platform` — the Mac mini's own OS —
+   *   instead of the runner's target. Deploying from the Mac to CT100 (a Debian LXC over
+   *   `sshSudoRunner`) dropped GNU's required `--`, and `sudo-allowlist-dir.ts`'s `dirProgramProblem`
+   *   refused every chown with `SudoRefusedError` even though the path was under a declared prefix.
+   *   `localRunner()`'s own local deploys never showed it: there, `process.platform` and the
+   *   target happen to be the same machine. This field is the fix: every call site that needs to
+   *   know the target's OS reads `runner.platform`, never `process.platform`.
+   */
+  readonly platform: HostPlatform;
   /**
    * ⛔ DECLARED, NEVER INFERRED. `true` only when this runner can do every root-needing call the
    *   providers make of it: every call already runs as root (a runner that talks to a root helper,

package/src/launchd/sudo-runner.ts

@@ -162,6 +162,9 @@ export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): H
     },
     lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
     lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ Forwarded, never hardcoded: this runner elevates on the SAME target `base` already
+    //   declared (localRunner's own machine), so it carries no opinion of its own.
+    platform: base.platform,
     // ★ True, so the providers let a system-domain job through to this runner (canActAsRoot).
     privileged: true,
     readFile: (path) => base.readFile(path),

package/src/linux/directory-lifecycle.ts

@@ -100,8 +100,18 @@ const octal = (mode: number) => mode.toString(8).padStart(3, '0');
  *   keep it. These paths are absolute, so the token is only an option guard.
  * ⛔ Linux keeps `--`. The sudo allowlist requires that exact token; dropping it there
  *   refuses the elevation.
+ * 🔴 INCIDENT, homeflare-ct100 2026-09-27: this used to decide on `process.platform` — the OS of
+ *   the machine RUNNING Alchemy — instead of `runner.platform`, the OS of the TARGET the runner
+ *   actually writes to. Deploying from the Mac mini (`darwin`) to CT100, a Debian LXC reached
+ *   over `sshSudoRunner`, dropped the required `--` and `sudo-allowlist-dir.ts`'s
+ *   `dirProgramProblem` refused every chown with `SudoRefusedError`, even though the path was
+ *   under a declared prefix — `localRunner()`'s own local (Mac-to-Mac) deploys never showed it,
+ *   because there `process.platform` and the target happen to be the same machine. Reading
+ *   `runner.platform` instead (declared by every HostRunner — see its own doc comment) makes the
+ *   decision follow the target, not the caller.
  */
-const chmodChownEnd = (): readonly string[] => (process.platform === 'darwin' ? [] : ['--']);
+const chmodChownEnd = (runner: HostRunner): readonly string[] =>
+  runner.platform === 'darwin' ? [] : ['--'];
 
 /** One program, checked: anything but exit 0 is an Error naming the argv and the host's words. */
 const must = async (runner: HostRunner, path: string, argv: readonly string[]): Promise<void> => {
@@ -160,7 +170,12 @@ export const reconcileDirectory = async (
     }
     await must(runner, props.path, ['mkdir', '-m', octal(want.mode), '--', props.path]);
   } else if (stat.mode !== want.mode) {
-    await must(runner, props.path, ['chmod', octal(want.mode), ...chmodChownEnd(), props.path]);
+    await must(runner, props.path, [
+      'chmod',
+      octal(want.mode),
+      ...chmodChownEnd(runner),
+      props.path,
+    ]);
   }
   /**
    * ★ Only when it is actually wrong. A `chown` that changes nothing is still a write on the host
@@ -174,7 +189,7 @@ export const reconcileDirectory = async (
     ? undefined
     : ownerArg(want);
   if (owner !== undefined)
-    await must(runner, props.path, ['chown', owner, ...chmodChownEnd(), props.path]);
+    await must(runner, props.path, ['chown', owner, ...chmodChownEnd(runner), props.path]);
   const after = await readDirectory(runner, props.path);
   // ⚠️ READ BACK: a runner that ignored the mode shows up here, not as a forever-`update`.
   if (after === undefined || after.mode !== want.mode || !ownerMatches(after, want)) {

package/src/linux/directory-sudo.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Host.Directory driven through sshSudoRunner — the exact path the homeflare-ct100 incident
+ * (2026-09-27) broke: a deploy running on a Mac (darwin) targeting a Linux host over ssh dropped
+ * the sudo allowlist's required `--`, because directory-lifecycle.ts's `chmodChownEnd()` read
+ * `process.platform` — the Mac's own OS — instead of the runner's own declared target.
+ *
+ * ★ WHY A SEPARATE FILE FROM directory.test.ts. Those tests exercise the lifecycle directly
+ *   against a bare fake host; these go through the REAL `sshSudoRunner` + `sudo-allowlist.ts`
+ *   layer (`canonicalize`, `dirProgramProblem`), which is what actually enforces the `--` token
+ *   and is what refused the live deploy with `SudoRefusedError`.
+ * ⛔ NEITHER TEST BELOW READS `process.platform`. `fakeLinuxHost()` (via `fakeSudoHost()`)
+ *   declares `platform: 'linux'` itself — sshRunner's own probe requires it — so this suite
+ *   catches the regression on every machine that runs `bun test`, regardless of that machine's
+ *   own OS. (This repo's own `check` job runs on `ubuntu-latest`, not the mini, so CI alone never
+ *   reproduces the "darwin process, Linux target" split the live incident measured; this suite's
+ *   fixed, declared target is what actually proves the fix, on any OS.)
+ */
+import { describe, expect, test } from 'bun:test';
+import { reconcileDirectory } from './directory-lifecycle.ts';
+import { fakeSudoHost } from './fake-sudo.ts';
+
+describe('Host.Directory through sshSudoRunner (a Linux target)', () => {
+  test('the elevated chown and chmod carry -- and the allowlist accepts them', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    expect(runner.platform).toBe('linux'); // ★ declared by sshRunner's own uname probe.
+
+    // A fresh create under a declared prefix: mkdir runs as root, then chown (owner/group
+    // declared) also runs as root — both routed through routeExec()/elevatedExec().
+    const created = await reconcileDirectory(runner, {
+      group: 0,
+      mode: 0o755,
+      owner: 0,
+      path: '/etc/systemd/system/hf-test-dir',
+    });
+    expect(created).toEqual({
+      gid: 0,
+      mode: 0o755,
+      path: '/etc/systemd/system/hf-test-dir',
+      uid: 0,
+    });
+
+    // A mode drift on the next reconcile routes an elevated chmod too.
+    await reconcileDirectory(
+      runner,
+      { group: 0, mode: 0o750, owner: 0, path: '/etc/systemd/system/hf-test-dir' },
+      created,
+    );
+
+    const chown = privileged().find((call) => call[0] === '/usr/bin/chown');
+    const chmod = privileged().find((call) => call[0] === '/usr/bin/chmod');
+    // ⛔ REGRESSION: before the fix, these two calls carried no `--` whenever `bun test` ran on a
+    //   Mac, and `sudo-allowlist-dir.ts`'s `dirProgramProblem` refused them with
+    //   `SudoRefusedError` — the exact failure measured against homeflare-ct100 2026-09-27.
+    expect(chown).toBeDefined();
+    expect(chown).toContain('--');
+    expect(chmod).toBeDefined();
+    expect(chmod).toContain('--');
+  });
+});

package/src/linux/directory.test.ts

@@ -3,6 +3,7 @@
  * to create a parent.
  */
 import { describe, expect, test } from 'bun:test';
+import type { HostRunner } from '../launchd/runner.ts';
 import {
   deleteDirectory,
   diffDirectory,
@@ -105,8 +106,16 @@ describe('drift', () => {
 });
 
 describe('argv', () => {
-  test('chmod and chown omit -- on Darwin; mkdir keeps it on every platform', async () => {
+  // ⛔ REGRESSION, 2026-09-27: this used to read `process.platform !== 'darwin'` to decide what
+  //   the fake (a LINUX host) should have produced — so it only ever proved the real behaviour
+  //   when `bun test` itself happened to run on Linux (matching the fake's target by
+  //   coincidence), and passed just as happily on a Mac while asserting the bug itself (no `--`
+  //   for a Linux target). `runner.platform` is declared by the fixture instead, so these two
+  //   tests hold regardless of what OS actually runs the suite — the exact "darwin process,
+  //   Linux target" split the homeflare-ct100 incident measured.
+  test('mkdir keeps --, and chmod/chown carry -- for a Linux target', async () => {
     const fake = host();
+    expect(fake.runner.platform).toBe('linux'); // ★ fakeLinuxHost's own declaration.
     const created = await reconcileDirectory(fake.runner, {
       group: 0,
       mode: 0o755,
@@ -118,13 +127,30 @@ describe('argv', () => {
       { group: 0, mode: 0o750, owner: 0, path: '/opt/app/bin' },
       created,
     );
-    const gnu = process.platform !== 'darwin';
-    const chown = fake.calls.find((call) => call[0] === 'chown');
-    const chmod = fake.calls.find((call) => call[0] === 'chmod');
-    const mkdir = fake.calls.find((call) => call[0] === 'mkdir');
-    expect(chown?.includes('--')).toBe(gnu);
-    expect(chmod?.includes('--')).toBe(gnu);
-    expect(mkdir).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'mkdir')).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'chown')).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'chmod')).toContain('--');
+  });
+
+  test('mkdir still keeps --, but chmod/chown omit it for a runner declared as Darwin', async () => {
+    const fake = host();
+    // ★ Same fake host, only the declared target changes — proves chmodChownEnd() reads
+    //   `runner.platform`, never the machine `bun test` itself happens to run on.
+    const darwinRunner: HostRunner = { ...fake.runner, platform: 'darwin' };
+    const created = await reconcileDirectory(darwinRunner, {
+      group: 0,
+      mode: 0o755,
+      owner: 0,
+      path: '/opt/app/bin',
+    });
+    await reconcileDirectory(
+      darwinRunner,
+      { group: 0, mode: 0o750, owner: 0, path: '/opt/app/bin' },
+      created,
+    );
+    expect(fake.calls.find((call) => call[0] === 'mkdir')).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'chown')?.includes('--')).toBe(false);
+    expect(fake.calls.find((call) => call[0] === 'chmod')?.includes('--')).toBe(false);
   });
 });
 

package/src/linux/fake-linux-host.ts

@@ -127,6 +127,8 @@ export const fakeLinuxHost = (options: FakeLinuxOptions = {}) => {
     lookupUser: async (nameOrId) =>
       options.users?.[nameOrId] ??
       Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    // ★ This fake models sshRunner()'s own target, which is always Linux — fixed, not an option.
+    platform: 'linux',
     privileged,
     readFile: async (path) => files.get(path)?.bytes,
     removeFile: async (path) => {

package/src/linux/index.ts

@@ -24,6 +24,7 @@ export { sshSudoRunner } from './sudo-runner.ts';
 export type {
   ExecResult,
   FileStat,
+  HostPlatform,
   HostRunner,
   HostUser,
   WriteOptions,

package/src/linux/ssh-runner.ts

@@ -154,6 +154,10 @@ export const sshRunner = async (options: SshRunnerOptions): Promise<HostRunner>
       const result = await run(execScript(userQuery('linux', nameOrId)));
       return result.exitCode === 0 ? parseUser('linux', result.stdout) : undefined;
     },
+    // ★ Fixed, not read from the caller's own `process.platform`: the probe above already
+    //   refused anything but `uname -s` = Linux, so this is the one true answer for this runner —
+    //   whatever OS is running Alchemy itself is irrelevant (HostRunner.platform's doc comment).
+    platform: 'linux',
     privileged: false,
     readFile: async (path) => {
       const result = await run(readScript(path));

package/src/linux/sudo-runner.ts

@@ -99,6 +99,9 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
     },
     lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
     lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ Forwarded, never hardcoded — same reasoning as ../launchd/sudo-runner.ts's own forward:
+    //   this runner elevates on the SAME target `base` (sshRunner) already declared.
+    platform: base.platform,
     privileged: true,
     readFile: (path) => base.readFile(path),
     removeFile: async (path) => {

package/src/opnsense/alias-form.test.ts

@@ -1,19 +1,21 @@
 /**
- * `alias-form.ts`'s pure functions against literal `AliasItem` fixtures — no network, no fake
- * server. Mirrors `../discord/command-form.ts`'s own test file in spirit.
+ * `alias-form.ts`'s pure functions against literal `ModelAliasReadItem` fixtures (the WHOLE-MODEL
+ * `get()`'s read-shaped item, option maps and all — OPNSENSE-2) — no network, no fake server.
+ * Mirrors `../discord/command-form.ts`'s own test file in spirit.
  */
 import { describe, expect, test } from 'bun:test';
 import type * as alias from '@distilled.cloud/opnsense/firewall_alias';
 import { attributesOf, matches } from './alias-form.ts';
 import type { AliasProps } from './alias.ts';
+import { optionMap } from './wire.ts';
 
 const UUID = '11111111-1111-1111-1111-111111111111';
 
-const liveHost = (overrides: Partial<alias.AliasItem> = {}): alias.AliasItem => ({
-  content: '10.20.10.1',
+const liveHost = (overrides: Partial<alias.ModelAliasReadItem> = {}): alias.ModelAliasReadItem => ({
+  content: optionMap('10.20.10.1'),
   enabled: '1',
   name: 'homeflare_edge',
-  type: 'host',
+  type: optionMap('host'),
   ...overrides,
 });
 
@@ -38,10 +40,20 @@ describe('alias-form attributesOf', () => {
     expect(attributesOf(UUID, liveHost({ enabled: '0' })).enabled).toBe(false);
   });
 
-  test('categories are split, sorted and deduplicated', () => {
-    const live = liveHost({ categories: 'c-two,c-one,c-one' });
+  test('categories are the selected keys, sorted and deduplicated', () => {
+    const live = liveHost({ categories: optionMap('c-two', 'c-one') });
     expect(attributesOf(UUID, live).categories).toEqual(['c-one', 'c-two']);
   });
+
+  test('an unselected option-map entry is not returned (single-select `type`)', () => {
+    const live = liveHost({
+      type: {
+        host: { value: 'Host(s)', selected: 1 },
+        network: { value: 'Network(s)', selected: 0 },
+      },
+    });
+    expect(attributesOf(UUID, live).type).toBe('host');
+  });
 });
 
 describe('alias-form matches', () => {
@@ -57,12 +69,12 @@ describe('alias-form matches', () => {
   });
 
   test('content drift is caught', () => {
-    const drifted = attributesOf(UUID, liveHost({ content: '10.20.10.2' }));
+    const drifted = attributesOf(UUID, liveHost({ content: optionMap('10.20.10.2') }));
     expect(matches(drifted, props)).toBe(false);
   });
 
   test('category order alone is not drift — both sides normalise through the same set', () => {
-    const live = attributesOf(UUID, liveHost({ categories: 'b,a' }));
+    const live = attributesOf(UUID, liveHost({ categories: optionMap('b', 'a') }));
     const declared: AliasProps = { ...props, categories: ['a', 'b'] };
     expect(matches(live, declared)).toBe(true);
   });
@@ -79,9 +91,9 @@ describe('propsFromLive round-trip — the declaration renderer whole contract',
     // alias.ts re-exports `attributesOf` itself as `propsFromLive`; tested directly here since
     // alias.ts also wires up the Resource machinery this file does not need to import.
     const live = liveHost({
-      categories: 'c-two,c-one',
-      content: '203.0.113.0/24',
-      type: 'network',
+      categories: optionMap('c-two', 'c-one'),
+      content: optionMap('203.0.113.0/24'),
+      type: optionMap('network'),
     });
     const rendered = attributesOf(UUID, live);
     expect(matches(attributesOf(UUID, live), rendered)).toBe(true);

package/src/opnsense/alias-form.ts

@@ -18,24 +18,37 @@
  */
 import type { AliasAttributes, AliasProps } from './alias.ts';
 import type * as alias from '@distilled.cloud/opnsense/firewall_alias';
-import { bool01, csvSet, csvSetOf, numField } from './wire.ts';
+import { bool01, csvSetOf, numField, selectedOf, selectedOneOf } from './wire.ts';
 
 /**
  * ★ ATTRIBUTES AND THE DECLARATION RENDERER ARE ONE FUNCTION. Attributes ARE exactly the props a
  *   noop declaration needs — see the exported `propsFromLive` alias in alias.ts's barrel and
  *   `alias-form.test.ts`'s round-trip test (`matches(attributesOf(uuid, live), attributesOf(uuid,
  *   live))` is always true by construction, and so is the general case).
+ *
+ * `live` is `ModelAliasReadItem` (the WHOLE-MODEL `get()`'s read-shaped item), not `AliasItem` —
+ * `type`/`interface`/`proto`/`categories` decode as option maps, not strings (OPNSENSE-2; see
+ * wire.ts's module doc). `selectedOf`/`selectedOneOf` extract the selected key(s) back to the
+ * same plain-string/string[] shape `AliasAttributes` already declared.
+ *
+ * `content` is `.\AliasContentField`, which overrides `getNodeData()` independently of
+ * `BaseListField` (`Firewall/FieldTypes/AliasContentField.php:69-76`) — it still decodes as a map,
+ * but every entry is unconditionally `selected: 1` (it is a raw newline-separated list, not a
+ * real option set), and ITS wire separator is `\n`, not `,`. `Object.keys` preserves the
+ * insertion order OPNsense's own `explode()` built the map in, which matters for a host/URL list
+ * in a way `selectedOf`'s alphabetical sort does not preserve — so this one field is reconstructed
+ * directly rather than through `selectedOf`.
  */
-export const attributesOf = (uuid: string, live: alias.AliasItem): AliasAttributes => ({
-  categories: csvSet(live.categories),
-  content: live.content ?? '',
+export const attributesOf = (uuid: string, live: alias.ModelAliasReadItem): AliasAttributes => ({
+  categories: selectedOf(live.categories),
+  content: Object.keys(live.content ?? {}).join('\n'),
   counters: bool01(live.counters, false),
   description: live.description ?? '',
   enabled: bool01(live.enabled, true),
-  interface: live.interface ?? '',
+  interface: selectedOneOf(live.interface),
   name: live.name,
-  proto: live.proto ?? '',
-  type: live.type,
+  proto: selectedOf(live.proto).join(','),
+  type: selectedOneOf(live.type),
   updatefreq: numField(live.updatefreq, 0),
   uuid,
 });