@homeflare/alchemy 0.38.0 → 0.40.0

package/src/talos/talos-bootstrap.ts

@@ -6,6 +6,22 @@
  *   the bootstrap node. This command must run exactly once per cluster.
  *
  * ⛔ NOT A FACTORY RESOURCE — bootstrap cannot be deleted or updated in place; `delete` is a no-op.
+ *
+ * ⛔ ONCE MEANS ONCE (K-talos-first-boot, 2026-09-26) — THE SHIPPED SHAPE COULD BOOTSTRAP A SECOND
+ *   etcd CLUSTER. The original `isBootstrapped` turned every read failure into `false`
+ *   (`Effect.orElseSucceed`), `diff` then planned `update`, and `reconcile` re-ran `talosctl
+ *   bootstrap` — Talos's only server-side guard is a non-empty etcd data directory (REASONED,
+ *   `v1alpha1_server.go:441`), so a reinstalled or reset bootstrap node re-bootstrapped a fresh,
+ *   isolated single-member cluster: split brain. Fixed per
+ *   docs/plans/2026-09-26-talos-stack-first-boot.md's "Bootstrap — once means once" section:
+ *     - `read` now answers presence/absence correctly instead of always returning a defined
+ *       object — `undefined` only from a SUCCESSFUL read that finds no members (cold-start
+ *       absence); a failing read propagates its error instead of being reinterpreted as absence.
+ *     - `diff` trusts `output.bootstrapped` once it is `true` and reports `noop` without touching
+ *       the live cluster at all — confirmation is `reconcile`'s job now, not plan's.
+ *     - `reconcile` checks `output?.bootstrapped` FIRST: once true, it NEVER calls `talosctl
+ *       bootstrap` again, no matter what a live read says. A live read that fails OR comes back
+ *       empty both raise the same `TalosReBootstrapRefused` — re-bootstrap is a human decision.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -14,11 +30,22 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { mintTalosconfig } from './credentials.ts';
 import type { TalosRequirements, WithTarget } from './resource.ts';
-import { talosctl, talosctlOrAlready } from './talosctl.ts';
+import { assertNoLivePeers, isBootstrapped } from './talos-bootstrap-etcd.ts';
+import { TalosReBootstrapRefused } from './talos-errors.ts';
+import { talosctlOrAlready } from './talosctl.ts';
 
 export interface BootstrapProps extends WithTarget {
   /** The ONE control-plane node that receives `talosctl bootstrap`. */
   node: string;
+  /**
+   * The OTHER declared control-plane nodes — never `node` itself. Optional, but a multi-control-
+   * plane cluster (decision 66: 3, one per TB4 node) SHOULD set it: `reconcileBootstrap`'s CREATE
+   * path (I4 fix, LAND red team, 2026-09-26) requires every one of these to show a successful,
+   * EMPTY etcd-members read before it will bootstrap `node` — the guard against re-bootstrapping a
+   * split-brain second cluster when this row's own state was lost. See talos-bootstrap-etcd.ts's
+   * `assertNoLivePeers`.
+   */
+  peers?: readonly string[];
   /** Machine configs for this node (and peers) must be applied first. */
   after?: readonly unknown[];
 }
@@ -42,54 +69,127 @@ export const TalosBootstrap = Resource<TalosBootstrap>('Talos.Bootstrap', {
 });
 
 /**
- * REASONED: `talosctl get etcdmembers -o json` should list members after bootstrap.
- * ⚠️ NOT MEASURED — first live deploy confirms the resource type name.
+ * ⛔ WRAPPED IN `Effect.scoped` (K-A3, 2026-09-26) — `mintTalosconfig` contributes `Scope.Scope`
+ *   to its own return type rather than closing its scope internally (the C1 fix, credentials.ts's
+ *   own header); this is the caller that owns the temp talosconfig's lifetime for the read.
+ *
+ * ⛔ ANSWERS PRESENCE/ABSENCE, NOT "attrs-or-error" (K-talos-first-boot, fixes the shipped shape).
+ *   `undefined` only when a read SUCCEEDS and finds no members — the honest "not created yet"
+ *   Alchemy's engine expects from a cold-start adoption probe. A failing read propagates instead
+ *   of being reinterpreted as absence — this is the fix `isBootstrapped` no longer hides.
+ *
+ * ★ EXPORTED (like proxmox/ceph-daemon.ts's `reconcileDaemon`, machine-config-read.ts's
+ *   `readMachineConfig`) so talos-bootstrap.test.ts calls it directly with a fake spawner instead
+ *   of driving it through the full Alchemy engine.
  */
-const isBootstrapped = (props: BootstrapProps, talosconfigPath: string) =>
-  talosctl(['get', 'etcdmembers', '-o', 'json'], {
-    nodes: [props.node],
-    talosconfigPath,
-  }).pipe(
-    Effect.map((text) => text.includes('"id"') || text.includes('"member"')),
-    Effect.orElseSucceed(() => false),
+export const readBootstrap = (props: BootstrapProps) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const credential = yield* mintTalosconfig(props.target);
+      const bootstrapped = yield* isBootstrapped(props, credential.talosconfigPath);
+      return bootstrapped ? ({ bootstrapped: true, node: props.node } as const) : undefined;
+    }),
   );
 
-const read = (props: BootstrapProps) =>
-  Effect.gen(function* () {
-    const credential = yield* mintTalosconfig(props.target);
-    const bootstrapped = yield* isBootstrapped(props, credential.talosconfigPath);
-    return { bootstrapped, node: props.node };
-  });
-
-const diff = (news: Input<BootstrapProps>, output: BootstrapAttributes | undefined) =>
+/**
+ * ⛔ TRUSTS STATE, NEVER TOUCHES THE LIVE CLUSTER (K-talos-first-boot) — once `output.bootstrapped`
+ *   is `true` this always reports `noop`, unconditionally, with zero live calls.
+ *
+ * ⛔ I3 CORRECTION (LAND red team, 2026-09-26) — THE OLD COMMENT HERE CLAIMED "confirming the
+ *   invariant against etcd is reconcile's job (every deploy calls it)". THAT IS FALSE, VERIFIED
+ *   against the pinned alchemy beta.79 source: Apply never reconciles a node whose diff came back
+ *   `noop` (`Apply.ts`'s `noop` branch just refreshes row metadata and signals ready — it does not
+ *   call `provider.reconcile` at all). This file's own `noop` above IS what skips it. So
+ *   `reconcileBootstrap`'s re-confirm branch (the one that raises `TalosReBootstrapRefused` on a
+ *   failed or empty read) never runs on an ordinary `plan`/`deploy` once `bootstrapped: true` is
+ *   recorded — only `--force` reaches it, by forcing a reconcile regardless of the plan action.
+ *   Safety still holds — `talosctl bootstrap` genuinely never re-runs while state exists — but a
+ *   reset control-plane node (etcd wiped, VM replaced) stays silently invisible to `plan` and
+ *   `deploy` alike until an operator runs `--force` or a verify pass.
+ *   ⚠️ NOT FIXED BY HAVING `diff` READ HERE TOO (the finding's other offered fix) — that would touch
+ *   the live cluster (and mint a talosconfig) on EVERY plan for an already-bootstrapped node, for a
+ *   scenario (a reset node) that a `configDigest`-style pinned check can't distinguish from a merely
+ *   slow/unreachable read; a single transient failure would then abort every future plan for a
+ *   healthy node, for no benefit — the exact cost the original (correct) half of this comment
+ *   already named. `MachineConfig`/`ClusterHealth`'s diffs DO mint and read live on every plan
+ *   (D2 puts that on the admin/operator lane, not agent), so this isn't a lane-access limit; it is
+ *   this resource's own choice to trust a `true` boolean forever rather than re-derive it from a
+ *   live signal that cannot yet tell "reset" apart from "briefly unreachable". Recorded as an open
+ *   gap for whoever builds the operator verify pass, not silently fixed here.
+ */
+export const diffBootstrap = (
+  news: Input<BootstrapProps>,
+  output: BootstrapAttributes | undefined,
+) =>
   Effect.gen(function* () {
     if (output === undefined || !isResolved(news)) return undefined;
-    const live = yield* read(news);
-    if (live.bootstrapped) return { action: 'noop' } as const;
-    return { action: 'update' } as const;
+    if (output.bootstrapped) return { action: 'noop' } as const;
+    const live = yield* readBootstrap(news);
+    return live?.bootstrapped === true
+      ? ({ action: 'noop' } as const)
+      : ({ action: 'update' } as const);
   });
 
-const reconcile = (props: BootstrapProps) =>
-  Effect.gen(function* () {
-    const credential = yield* mintTalosconfig(props.target);
-    const before = yield* isBootstrapped(props, credential.talosconfigPath);
-    if (!before) {
-      yield* talosctlOrAlready(['bootstrap'], {
-        nodes: [props.node],
-        talosconfigPath: credential.talosconfigPath,
-      });
-    }
-    const after = yield* isBootstrapped(props, credential.talosconfigPath);
-    if (!after) {
-      return yield* Effect.die(
-        new Error(
-          `${props.node}: bootstrap returned no error but etcd members are still absent. ` +
-            'Read back rather than trusting the exit code alone.',
-        ),
-      );
-    }
-    return { bootstrapped: true, node: props.node };
-  });
+/**
+ * ⛔ ONCE MEANS ONCE — see this file's own header. `output?.bootstrapped === true` is checked
+ *   BEFORE anything else, and that branch never builds a `talosctl bootstrap` argv at all — the
+ *   confirmation read below can fail, or succeed and say "absent", and EITHER way this raises
+ *   `TalosReBootstrapRefused` rather than treating "absent" as licence to bootstrap again.
+ */
+export const reconcileBootstrap = (
+  props: BootstrapProps,
+  output: BootstrapAttributes | undefined,
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const credential = yield* mintTalosconfig(props.target);
+
+      if (output?.bootstrapped === true) {
+        const stillBootstrapped = yield* isBootstrapped(props, credential.talosconfigPath).pipe(
+          Effect.catchIf(
+            (): boolean => true,
+            (cause) =>
+              Effect.fail(
+                new TalosReBootstrapRefused({
+                  detail: `live read failed: ${String(cause)}`,
+                  node: props.node,
+                }),
+              ),
+          ),
+        );
+        if (!stillBootstrapped) {
+          return yield* Effect.fail(
+            new TalosReBootstrapRefused({
+              detail: 'etcd members are absent on a live read against already-bootstrapped state',
+              node: props.node,
+            }),
+          );
+        }
+        return { bootstrapped: true, node: props.node };
+      }
+
+      const before = yield* isBootstrapped(props, credential.talosconfigPath);
+      if (!before) {
+        // ⛔ I4 FIX (LAND red team) — see BootstrapProps.peers's own doc and
+        // talos-bootstrap-etcd.ts's assertNoLivePeers header.
+        yield* assertNoLivePeers(props, credential.talosconfigPath);
+        yield* talosctlOrAlready(['bootstrap'], {
+          nodes: [props.node],
+          talosconfigPath: credential.talosconfigPath,
+        });
+      }
+      const after = yield* isBootstrapped(props, credential.talosconfigPath);
+      if (!after) {
+        return yield* Effect.die(
+          new Error(
+            `${props.node}: bootstrap returned no error but etcd members are still absent. ` +
+              'Read back rather than trusting the exit code alone.',
+          ),
+        );
+      }
+      return { bootstrapped: true, node: props.node };
+    }),
+  );
 
 const handlers = {
   delete: () => Effect.void,
@@ -99,10 +199,16 @@ const handlers = {
   }: {
     news: Input<BootstrapProps>;
     output: BootstrapAttributes | undefined;
-  }) => diff(news, output),
+  }) => diffBootstrap(news, output),
   list: () => Effect.succeed([]),
-  read: ({ olds }: { olds: BootstrapProps }) => read(olds),
-  reconcile: ({ news }: { news: BootstrapProps }) => reconcile(news),
+  read: ({ olds }: { olds: BootstrapProps }) => readBootstrap(olds),
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: BootstrapProps;
+    output: BootstrapAttributes | undefined;
+  }) => reconcileBootstrap(news, output),
 };
 
 export const TalosBootstrapProvider = () =>

package/src/talos/talos-cluster-health.test.ts

@@ -0,0 +1,143 @@
+/**
+ * `Talos.ClusterHealth` — no swallowed transport errors (K-talos-first-boot). Fully offline:
+ * fake-process.ts fakes `bao`/`talosctl`, nothing real spawns.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import {
+  diffClusterHealth,
+  readClusterHealth,
+  reconcileClusterHealth,
+} from './talos-cluster-health.ts';
+
+const TARGET = { cluster: 'c1', mount: 'talos-c1' };
+const props = () => ({ controlPlaneNodes: ['198.51.100.10'], target: TARGET });
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  handler: (c: FakeCall) => { stdout?: string; stderr?: string; exitCode?: number },
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(handler, calls),
+    ),
+  );
+
+const baoOk = (call: FakeCall) =>
+  call.command === 'bao'
+    ? { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) }
+    : undefined;
+
+/** `talosctl health` ran and reported unhealthy — the one case this family may call "not healthy". */
+const unhealthy = (call: FakeCall) =>
+  baoOk(call) ?? { exitCode: 1, stderr: 'kube-proxy not ready' };
+
+/** `talosctl health` ran and reported healthy. */
+const healthy = (call: FakeCall) => baoOk(call) ?? {};
+
+/** `bao` itself fails — a transport/credential problem, not a cluster-health verdict. */
+const vaultDown = (call: FakeCall) =>
+  call.command === 'bao' ? { exitCode: 1, stderr: 'permission denied' } : {};
+
+describe('readClusterHealth', () => {
+  it('reports healthy:false when talosctl health ran and exited non-zero', async () => {
+    const result = await run(readClusterHealth(props()), unhealthy);
+    assert.equal(result.healthy, false);
+  });
+
+  it('reports healthy:true when talosctl health exits zero', async () => {
+    const result = await run(readClusterHealth(props()), healthy);
+    assert.equal(result.healthy, true);
+  });
+
+  it('propagates a vault/transport failure instead of reporting healthy:false', async () => {
+    await assert.rejects(
+      run(readClusterHealth(props()), vaultDown),
+      (error: unknown) => error instanceof Error && error.message.includes('permission denied'),
+    );
+  });
+});
+
+describe('diffClusterHealth', () => {
+  it('plans update when the cluster genuinely reports unhealthy', async () => {
+    const result = await run(
+      diffClusterHealth(props(), {
+        controlPlaneNodes: '198.51.100.10',
+        healthy: false,
+        workerNodes: '',
+      }),
+      unhealthy,
+    );
+    assert.equal(result?.action, 'update');
+  });
+
+  it('propagates a vault/transport failure rather than planning update silently', async () => {
+    await assert.rejects(
+      run(
+        diffClusterHealth(props(), {
+          controlPlaneNodes: '198.51.100.10',
+          healthy: false,
+          workerNodes: '',
+        }),
+        vaultDown,
+      ),
+    );
+  });
+});
+
+describe('check — I1 fix: --nodes names ONE contact node, not the whole cluster', () => {
+  it('targets only the first control-plane node with --nodes/--endpoints, but lists all of them under --control-plane-nodes', async () => {
+    const calls: FakeCall[] = [];
+    await run(
+      readClusterHealth({
+        controlPlaneNodes: ['198.51.100.10', '198.51.100.11', '198.51.100.12'],
+        target: TARGET,
+      }),
+      healthy,
+      calls,
+    );
+    const talosctlCall = calls.find((c) => c.command === 'talosctl');
+    assert.ok(talosctlCall);
+    // ⛔ talosctl v1.13.8, measured: `health --nodes <ip1>,<ip2>` exits with "command \"health\" is
+    // not supported with multiple nodes" — exactly one contact node may ever reach --nodes.
+    const nodesIdx = talosctlCall.args.indexOf('--nodes');
+    assert.equal(talosctlCall.args[nodesIdx + 1], '198.51.100.10');
+    const endpointsIdx = talosctlCall.args.indexOf('--endpoints');
+    assert.equal(talosctlCall.args[endpointsIdx + 1], '198.51.100.10');
+    const cpIdx = talosctlCall.args.indexOf('--control-plane-nodes');
+    assert.equal(talosctlCall.args[cpIdx + 1], '198.51.100.10,198.51.100.11,198.51.100.12');
+  });
+
+  it('fails closed instead of spawning talosctl when controlPlaneNodes is empty', async () => {
+    await assert.rejects(
+      run(readClusterHealth({ controlPlaneNodes: [], target: TARGET }), healthy),
+      (error: unknown) =>
+        error instanceof Error && error.message.includes('controlPlaneNodes is empty'),
+    );
+  });
+});
+
+describe('reconcileClusterHealth', () => {
+  it('wraps a TalosError with a "cluster not healthy" message', async () => {
+    await assert.rejects(
+      run(reconcileClusterHealth(props()), unhealthy),
+      (error: unknown) => error instanceof Error && error.message.includes('cluster not healthy'),
+    );
+  });
+
+  it('propagates a vault/transport failure WITHOUT the "cluster not healthy" mislabel', async () => {
+    await assert.rejects(
+      run(reconcileClusterHealth(props()), vaultDown),
+      (error: unknown) =>
+        error instanceof Error &&
+        error.message.includes('permission denied') &&
+        !error.message.includes('cluster not healthy'),
+    );
+  });
+});

package/src/talos/talos-cluster-health.ts

@@ -6,6 +6,22 @@
  *
  * ⚠️ PLAN READS USE A SHORT TIMEOUT SO `plan` DOES NOT BLOCK TWENTY MINUTES. Reconcile uses the
  *   declared timeout — that is the deploy gate, not the plan gate.
+ *
+ * ⛔ THIS RESOURCE ASSUMES A CNI IS ALREADY RUNNING (K-talos-first-boot, 2026-09-26). The default
+ *   `talosctl health` suite checks nodes Ready, kube-proxy and CoreDNS, and Talos's own source
+ *   comment says these wait on the CNI (REASONED, `pkg/cluster/check/default.go:28-60,89-91`;
+ *   docs/plans/2026-09-26-talos-stack-first-boot.md's "CNI ordering" section). A consuming stack's
+ *   `after` MUST include the Cilium install step, not just `Talos.Bootstrap`/`Talos.Kubeconfig` —
+ *   declaring this row directly after bootstrap deadlocks into the `--wait-timeout` on every first
+ *   deploy, because Argo CD itself needs pod networking before it can install Cilium. Row order:
+ *   Bootstrap → Kubeconfig → Cilium (inline manifests in the seeded machine config, D-S2) →
+ *   `Talos.ClusterHealth`.
+ * ⛔ NO SWALLOWED TRANSPORT ERRORS (K-talos-first-boot) — the shipped `read` caught EVERY error
+ *   from `check()`, including a `mintTalosconfig`/`bao` failure, into a plain `healthy: false`. A
+ *   vault outage would then read as "cluster not healthy yet" — an operator chasing a Cilium
+ *   rollout would never learn the real problem was vault. Both `read` and `reconcile` now only
+ *   catch `TalosError` (`talosctl health` itself ran and exited non-zero — the one case this
+ *   family may honestly call "not healthy"); anything else propagates untouched.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -14,7 +30,7 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { mintTalosconfig } from './credentials.ts';
 import type { TalosRequirements, WithTarget } from './resource.ts';
-import { talosctl } from './talosctl.ts';
+import { TalosError, talosctl } from './talosctl.ts';
 
 export interface ClusterHealthProps extends WithTarget {
   /** Control-plane node IPs passed to `--control-plane-nodes`. */
@@ -27,7 +43,11 @@ export interface ClusterHealthProps extends WithTarget {
    * ⚠️ REASONED default — not measured here.
    */
   waitTimeout?: string;
-  /** Bootstrap and kubeconfig should complete before health is enforced. */
+  /**
+   * Ordering edge. ⛔ MUST reach past `Talos.Bootstrap`/`Talos.Kubeconfig` all the way through the
+   * Cilium CNI install (this file's own header, "CNI ordering") — the default health checks wait
+   * on kube-proxy and CoreDNS, both of which wait on a CNI that does not exist yet at bootstrap.
+   */
   after?: readonly unknown[];
 }
 
@@ -59,45 +79,88 @@ const healthArgs = (props: ClusterHealthProps, waitTimeout: string) => {
   return args;
 };
 
+/**
+ * ⛔ WRAPPED IN `Effect.scoped` (K-A3, 2026-09-26) — `mintTalosconfig` contributes `Scope.Scope`
+ *   to its own return type rather than closing its scope internally (the C1 fix, credentials.ts's
+ *   own header); both `read` and `reconcile` call this one function, so wrapping it here covers
+ *   both callers.
+ * ⛔ I1 FIX (LAND red team, 2026-09-26) — `--nodes` NAMES ONE CONTACT NODE, NOT THE WHOLE CLUSTER.
+ *   MEASURED against local talosctl v1.13.8 (unroutable TEST-NET addresses): `talosctl health
+ *   --nodes <ip1>,<ip2>` fails with `command "health" is not supported with multiple nodes` — the
+ *   shipped code passed EVERY control-plane node as `--nodes`, so with decision 66's 3-node layout
+ *   this command could never succeed even against a genuinely healthy cluster: `read` always
+ *   reported `healthy:false`, `diff` always planned `update`, and `reconcile` always failed with a
+ *   misleading "not healthy within Nm". Fixed: the first control-plane node is the sole `--nodes`/
+ *   `--endpoints` contact point (talosctl proxies the actual check through it); the FULL node lists
+ *   still go to `--control-plane-nodes`/`--worker-nodes` via `healthArgs`, which is what `talosctl
+ *   health` actually checks the health OF.
+ */
 const check = (props: ClusterHealthProps, waitTimeout: string) =>
-  Effect.gen(function* () {
-    const credential = yield* mintTalosconfig(props.target);
-    yield* talosctl(healthArgs(props, waitTimeout), {
-      nodes: [...props.controlPlaneNodes],
-      talosconfigPath: credential.talosconfigPath,
-    });
-    return {
-      controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
-      healthy: true,
-      workerNodes: nodeCsv(props.workerNodes),
-    };
-  });
+  Effect.scoped(
+    Effect.gen(function* () {
+      const credential = yield* mintTalosconfig(props.target);
+      const contact = props.controlPlaneNodes[0];
+      if (contact === undefined) {
+        return yield* Effect.fail(
+          new Error(
+            `Talos.ClusterHealth ${props.target.cluster}: controlPlaneNodes is empty — need at ` +
+              'least one node to contact.',
+          ),
+        );
+      }
+      yield* talosctl(healthArgs(props, waitTimeout), {
+        endpoints: [contact],
+        nodes: [contact],
+        talosconfigPath: credential.talosconfigPath,
+      });
+      return {
+        controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
+        healthy: true,
+        workerNodes: nodeCsv(props.workerNodes),
+      };
+    }),
+  );
+
+/**
+ * ⛔ CATCHES ONLY `TalosError` (K-talos-first-boot) — a run of `talosctl health` that itself
+ *   completed and exited non-zero, which is the only outcome this family may honestly call "not
+ *   healthy yet". Anything else (a `mintTalosconfig`/`bao` failure, a JS defect) propagates instead
+ *   of masquerading as an unhealthy cluster — see this file's own header.
+ */
+const isTalosError = (cause: unknown): cause is TalosError => cause instanceof TalosError;
 
-const read = (props: ClusterHealthProps) =>
+/** ★ EXPORTED for talos-cluster-health.test.ts — see talos-bootstrap.ts's own note on the pattern. */
+export const readClusterHealth = (props: ClusterHealthProps) =>
   check(props, '5s').pipe(
-    Effect.orElseSucceed(() => ({
-      controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
-      healthy: false,
-      workerNodes: nodeCsv(props.workerNodes),
-    })),
+    Effect.catchIf(isTalosError, () =>
+      Effect.succeed({
+        controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
+        healthy: false,
+        workerNodes: nodeCsv(props.workerNodes),
+      }),
+    ),
   );
 
-const diff = (news: Input<ClusterHealthProps>, output: ClusterHealthAttributes | undefined) =>
+export const diffClusterHealth = (
+  news: Input<ClusterHealthProps>,
+  output: ClusterHealthAttributes | undefined,
+) =>
   Effect.gen(function* () {
     if (output === undefined || !isResolved(news)) return undefined;
-    const live = yield* read(news);
+    const live = yield* readClusterHealth(news);
     if (live.healthy) return { action: 'noop' } as const;
     return { action: 'update' } as const;
   });
 
-const reconcile = (props: ClusterHealthProps) =>
+export const reconcileClusterHealth = (props: ClusterHealthProps) =>
   check(props, props.waitTimeout ?? '20m0s').pipe(
-    Effect.mapError(
-      (cause) =>
+    Effect.catchIf(isTalosError, (cause) =>
+      Effect.fail(
         new Error(
           `Talos.ClusterHealth ${props.target.cluster}: cluster not healthy within ` +
             `${props.waitTimeout ?? '20m0s'} — ${String(cause)}`,
         ),
+      ),
     ),
   );
 
@@ -109,10 +172,10 @@ const handlers = {
   }: {
     news: Input<ClusterHealthProps>;
     output: ClusterHealthAttributes | undefined;
-  }) => diff(news, output),
+  }) => diffClusterHealth(news, output),
   list: () => Effect.succeed([]),
-  read: ({ olds }: { olds: ClusterHealthProps }) => read(olds),
-  reconcile: ({ news }: { news: ClusterHealthProps }) => reconcile(news),
+  read: ({ olds }: { olds: ClusterHealthProps }) => readClusterHealth(olds),
+  reconcile: ({ news }: { news: ClusterHealthProps }) => reconcileClusterHealth(news),
 };
 
 export const TalosClusterHealthProvider = () =>

package/src/talos/talos-errors.ts

@@ -0,0 +1,85 @@
+/**
+ * `Talos.MachineConfig`'s typed failures — split out of talos-machine-config.ts (2026-09-26,
+ * K-A3) for the same reason proxmox/credential-errors.ts gives: keep a class's own header out of
+ * the 250-line budget of the file that raises it.
+ */
+import * as Data from 'effect/Data';
+import type { ApplyMode } from './resource.ts';
+
+/**
+ * The OpenBao KV content at `mount/key` does not hash to the pinned `configDigest`.
+ *
+ * ★ FAIL CLOSED, NO SPAWN — docs/plans/2026-09-26-talos-secrets-flow.md's O-A: "a poisoned or
+ *   fat-fingered KV write cannot silently reach a node". Raised BEFORE any talosctl process
+ *   starts, so a mismatch never sends an unpinned config anywhere — see reconcile() in
+ *   talos-machine-config.ts, which checks this ahead of minting the talosconfig credential too.
+ * ⛔ NEITHER DIGEST IN THIS MESSAGE IS THE CONFIG. Both are sha256 hex digests — safe to log,
+ *   safe to persist — never the KV content itself.
+ */
+export class TalosConfigDigestMismatch extends Data.TaggedError('TalosConfigDigestMismatch')<{
+  readonly mount: string;
+  readonly key: string;
+  readonly expected: string;
+  readonly got: string;
+}> {
+  override get message(): string {
+    return (
+      `${this.mount}/${this.key}: live content digest ${this.got} does not match the pinned ` +
+      `configDigest ${this.expected}. Fail closed — nothing was sent to talosctl. Either the KV ` +
+      'value was rewritten without a matching PR, or the pinned digest is stale; check which one ' +
+      'moved before re-pinning either side.'
+    );
+  }
+}
+
+/**
+ * `apply-config` returned success but the live machineconfig digest never matched the pin within
+ * the bounded poll (machine-config-poll.ts). See
+ * docs/plans/2026-09-26-talos-stack-first-boot.md's "Converged" section.
+ *
+ * ⛔ THIS IS THE REPLACEMENT FOR A SILENT `converged: false`. The shipped code let a read
+ *   failure during convergence checking disguise itself as "not converged yet" forever
+ *   (`orElseSucceed`); this type makes cap expiry a refusal an operator sees, not a plan that
+ *   quietly retries the same apply on every future run.
+ */
+export class TalosConvergenceTimeout extends Data.TaggedError('TalosConvergenceTimeout')<{
+  readonly node: string;
+  readonly mode: ApplyMode;
+  readonly attempts: number;
+}> {
+  override get message(): string {
+    return (
+      `${this.node}: apply-config (--mode ${this.mode}) was accepted but the live machineconfig ` +
+      `digest never matched the pin within ${this.attempts} bounded poll attempts. Refusing to ` +
+      'report converged — hand this node to the operator rather than silently pass.'
+    );
+  }
+}
+
+/**
+ * `Talos.Bootstrap` reconcile found state already recording `bootstrapped: true`, and a live
+ * check against etcd could not reconfirm it — either the read itself failed (`detail` carries the
+ * propagated cause), or it succeeded and came back with no members.
+ *
+ * ★ K-talos-first-boot's "once means once" — docs/plans/2026-09-26-talos-stack-first-boot.md's own
+ *   section of that name. EITHER cause raises this SAME typed error, and both ways `talosctl
+ *   bootstrap` is never spawned a second time: re-running it against a node that lost its etcd
+ *   data (a VM replace, a reset) forms a second, isolated single-member etcd cluster instead of
+ *   rejoining the existing one (REASONED, `v1alpha1_server.go:441` — Talos's only server-side
+ *   guard is a non-empty data directory, not "did this cluster already bootstrap"). That is split
+ *   brain, and nothing here can tell a genuinely reset node (needs its own operator-run recovery)
+ *   apart from a merely slow or unreachable read (needs a retry) — so both refuse alike and hand
+ *   the node to a human instead of guessing.
+ */
+export class TalosReBootstrapRefused extends Data.TaggedError('TalosReBootstrapRefused')<{
+  readonly node: string;
+  readonly detail: string;
+}> {
+  override get message(): string {
+    return (
+      `${this.node}: state already recorded a successful bootstrap, and a live check could not ` +
+      `reconfirm it (${this.detail}). Refusing to run 'talosctl bootstrap' again — that risks a ` +
+      'second, isolated etcd cluster on a reset node. This needs an operator, not a reconcile.'
+    );
+  }
+}