@homeflare/alchemy 0.39.0 → 0.40.0

package/src/talos/kubeconfig.ts

@@ -5,37 +5,53 @@
  *   `--merge=false` keeps it isolated; `-f/--force` overwrites an existing file.
  *
  * ⛔ THE KUBECONFIG FILE CONTAINS A CLIENT CERTIFICATE — IT MUST NOT BE AN ATTRIBUTE. Alchemy
- *   persists attributes unencrypted. This resource:
- *     - writes the file to `runtimePath` at reconcile time (re-minted each deploy),
- *     - persists ONLY public metadata + fingerprints,
- *     - exposes a `connection` field referencing the runtime path for `Kubernetes.ClusterAdapter`.
+ *   persists attributes unencrypted. This resource persists ONLY public metadata + fingerprints,
+ *   never the file's own bytes.
  *
- * ⚠️ `runtimePath` IS PERSISTED AS A STRING, NOT AS FILE CONTENTS. The path is a contract between
- *   this resource and the host filesystem — same pattern as pointing Kubernetes.KubeConfig at
- *   `/opt/homeflare/...` rendered outside Postgres.
+ * ⛔ LANDS IN OPENBAO, NOT A HOST `runtimePath` (K-talos-first-boot, 2026-09-26). The shipped shape
+ *   wrote a cluster-admin kubeconfig to un-vaulted host disk and never removed it — the exact class
+ *   of exposure `talos/credentials.ts`'s own header exists to prevent — and its own `read` depended
+ *   on that file's continued presence, so verifying from any other host planned `update` forever
+ *   (docs/plans/2026-09-26-talos-secrets-flow.md's "Measured today" section). Fixed:
+ *     - CREATE (`output === undefined`) runs `talosctl kubeconfig` into a throwaway, unguessable
+ *       temp path (this file's own `reservedTempPath`), reads it back, and writes its bytes into
+ *       OpenBao at `target.mount`/`kubeconfigKey` via stdin (`credentials-write.ts`'s
+ *       `writeKvValue` — ⛔ never argv) — never to any path a caller could depend on.
+ *     - ⛔ WRITTEN ONCE, NOT RE-MINTED EVERY DEPLOY. `talosctl kubeconfig` always issues a FRESH
+ *       admin client certificate; re-running it every reconcile would rotate credentials for no
+ *       reason and violate O1's write-once-at-bring-up grant on this one key
+ *       (docs/plans/2026-09-26-talos-secrets-flow.md, O1). Once `output` is defined, reconcile only
+ *       reads the vault copy back to confirm it — the same "once" shape `talos-bootstrap.ts` uses
+ *       for a boolean, here for a value.
+ *     - The persisted `connection` carries no usable host path — a consumer materializes its own
+ *       temp file via `credentials.ts`'s `mintKubeconfig`, the same pattern `mintTalosconfig`
+ *       already established. Wiring `Kubernetes.ClusterAdapter` to call it is separate, later work
+ *       (named, not built, in the secrets-flow doc); this only makes the vault-backed read+mint
+ *       step exist for it to call. ⛔ Until that wiring lands, `connection.auth.path` is a sentinel
+ *       that can never resolve to a real file (LAND red team I2, `kubeconfig-attrs.ts`'s own
+ *       header) — an ABSENT path here would let the stock `Kubernetes.KubeConfigAdapter` silently
+ *       fall back to `$KUBECONFIG`/`~/.kube/config` instead of failing loudly.
  */
+import { chmodSync } from 'node:fs';
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import type { Connection } from 'alchemy/Kubernetes/Connection';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { mintTalosconfig } from './credentials.ts';
+import { DEFAULT_KUBECONFIG_KEY, mintTalosconfig, readKvValue } from './credentials.ts';
+import { reservedTempPath, writeKvValue } from './credentials-write.ts';
+import { buildAttrs } from './kubeconfig-attrs.ts';
 import type { TalosRequirements, WithTarget } from './resource.ts';
 import { talosctl } from './talosctl.ts';
-import { kubeconfigMetadata, sha256 } from './values.ts';
 
 export interface KubeconfigProps extends WithTarget {
   /** Node that serves `talosctl kubeconfig`. */
   node: string;
   /** Context name inside the generated kubeconfig — not secret. */
   context: string;
-  /**
-   * Host path where talosctl writes the kubeconfig each reconcile.
-   *
-   * ⛔ Must be outside Alchemy state and rotated by redeploy, never copied into attributes.
-   */
-  runtimePath: string;
+  /** OpenBao KV path under `target.mount` for the written kubeconfig. Default `'kubeconfig'`. */
+  kubeconfigKey?: string;
   after?: readonly unknown[];
 }
 
@@ -50,7 +66,11 @@ export interface KubeconfigAttributes {
    * Serializable `Kubernetes.Connection` for downstream workloads.
    *
    * ★ auth.kind `kubeconfig` is the stock ClusterAdapter — provider-roadmap.md names this seam.
-   *   Only `path` and `context` appear here; the adapter reads credentials from disk at call time.
+   *   `path` is a sentinel that can never resolve (LAND red team I2, `kubeconfig-attrs.ts`'s own
+   *   `toConnection` header): the content lives in OpenBao, not at a fixed host path, and a real
+   *   `Kubernetes.ClusterAdapter` wiring is later work, so this must fail rather than silently
+   *   reach the operator's own kubeconfig. A consumer materializes its own scoped temp file via
+   *   `credentials.ts`'s `mintKubeconfig` in the meantime.
    */
   connection: Connection;
 }
@@ -65,92 +85,146 @@ export interface TalosKubeconfig extends Resource<
 
 export const TalosKubeconfig = Resource<TalosKubeconfig>('Talos.Kubeconfig');
 
-const generation = (meta: {
-  endpoint: string;
-  caFingerprint: string;
-  clientFingerprint: string;
-  context: string;
-}) => sha256(`${meta.context}\n${meta.endpoint}\n${meta.caFingerprint}\n${meta.clientFingerprint}`);
+/**
+ * ★ MEASURED AGAINST OPENBAO v2.6.2 (C1 fix, LAND red team, 2026-09-26 — isolated in-memory dev
+ *   server, `env -i`, scratch HOME, no estate credentials; server removed after): `bao kv get` on a
+ *   genuinely unwritten KV-v2 key exits 2 with stderr exactly `No value found at <mount>/data/<key>`
+ *   — `readKvValue`'s Error message embeds that text verbatim. This is the ONLY signal this file
+ *   trusts as "not written yet"; every other failure (a wrong exit code, a different stderr such as
+ *   a permission denial or a network failure) propagates as a real error instead of being read as
+ *   absence.
+ */
+const isVaultKeyAbsent = (error: unknown): boolean =>
+  error instanceof Error && /no value found at/i.test(error.message);
 
-const toConnection = (props: KubeconfigProps): Connection => ({
-  auth: { context: props.context, kind: 'kubeconfig', path: props.runtimePath },
-});
+const readVaultMeta = (props: KubeconfigProps, key: string) =>
+  readKvValue(props.target.mount, key, ['kubeconfig', 'config']).pipe(
+    Effect.catchIf(isVaultKeyAbsent, () => Effect.succeed(undefined)),
+  );
 
-const readFileMeta = (props: KubeconfigProps) =>
+/**
+ * ★ EXPORTED for kubeconfig.test.ts — see talos-bootstrap.ts's own note on the pattern.
+ *
+ * ⛔ C1 FIX (LAND red team, 2026-09-26) — `undefined` NOW MEANS ONLY "the key has never been
+ *   written", NEVER "some read failed". The shipped `Effect.orElseSucceed` folded EVERY failure —
+ *   including a vault outage or wrong mount — into a defined, empty-fingerprint object. Alchemy's
+ *   engine always adopts a defined cold-start `read` result and forces `update` (alchemy beta.79
+ *   `Plan.ts:1303-1352`), so `reconcileKubeconfig`'s write-once branch (`output !== undefined`)
+ *   then tried to CONFIRM a key that had never actually been written, and failed every time —
+ *   `Talos.Kubeconfig` could never be created. Vault content that EXISTS but does not parse as a
+ *   kubeconfig is a different, fail-closed case (below), never treated as absence.
+ */
+export const readKubeconfig = (props: KubeconfigProps) =>
   Effect.gen(function* () {
-    const text = yield* Effect.tryPromise({
-      try: () => Bun.file(props.runtimePath).text(),
-      catch: (cause) => new Error(String(cause)),
-    }).pipe(Effect.orElseSucceed(() => undefined as string | undefined));
-    if (text === undefined) return undefined;
-    const meta = kubeconfigMetadata(text, props.context);
-    if (meta === undefined) return undefined;
-    return {
-      certificateAuthorityFingerprint: meta.caFingerprint,
-      clientCertificateFingerprint: meta.clientFingerprint,
-      connection: toConnection(props),
-      context: props.context,
-      credentialGeneration: generation({ ...meta, context: props.context }),
-      endpoint: meta.endpoint,
-    };
+    const key = props.kubeconfigKey ?? DEFAULT_KUBECONFIG_KEY;
+    const raw = yield* readVaultMeta(props, key);
+    if (raw === undefined) return undefined;
+    const meta = buildAttrs(raw, props);
+    if (meta === undefined) {
+      return yield* Effect.fail(
+        new Error(
+          `${props.target.mount}/${key}: vault content exists but does not parse as a kubeconfig ` +
+            `for context ${props.context} — not a cold start. Fix the KV entry or the pinned ` +
+            'context rather than trusting an empty read.',
+        ),
+      );
+    }
+    return meta;
   });
 
-const read = (props: KubeconfigProps) =>
-  readFileMeta(props).pipe(
-    Effect.map((meta) =>
-      meta === undefined
-        ? {
-            certificateAuthorityFingerprint: '',
-            clientCertificateFingerprint: '',
-            connection: toConnection(props),
-            context: props.context,
-            credentialGeneration: '',
-            endpoint: '',
-          }
-        : meta,
-    ),
-  );
-
-const diff = (news: Input<KubeconfigProps>, output: KubeconfigAttributes | undefined) =>
+export const diffKubeconfig = (
+  news: Input<KubeconfigProps>,
+  output: KubeconfigAttributes | undefined,
+) =>
   Effect.gen(function* () {
     if (output === undefined || !isResolved(news)) return undefined;
-    const live = yield* read(news);
+    const live = yield* readKubeconfig(news);
     if (
-      live.credentialGeneration !== '' &&
-      output.credentialGeneration === live.credentialGeneration &&
-      output.context === live.context &&
-      output.endpoint === live.endpoint
+      live !== undefined &&
+      live.credentialGeneration === output.credentialGeneration &&
+      live.context === output.context &&
+      live.endpoint === output.endpoint
     ) {
       return { action: 'noop' } as const;
     }
     return { action: 'update' } as const;
   });
 
-const reconcile = (props: KubeconfigProps) =>
-  Effect.gen(function* () {
-    const credential = yield* mintTalosconfig(props.target);
-    yield* talosctl(
-      [
-        'kubeconfig',
-        props.runtimePath,
-        '--merge=false',
-        '--force',
-        '--force-context-name',
-        props.context,
-      ],
-      { nodes: [props.node], talosconfigPath: credential.talosconfigPath },
-    );
-    const meta = yield* readFileMeta(props);
-    if (meta === undefined) {
-      return yield* Effect.die(
-        new Error(
-          `${props.runtimePath}: talosctl kubeconfig returned no error but the file is missing ` +
-            'or unparsable. Read back rather than trusting the exit code alone.',
-        ),
+/**
+ * ⛔ WRAPPED IN `Effect.scoped` — same C1-lifetime reasoning as every other Talos resource file:
+ *   `mintTalosconfig` and `reservedTempPath` both contribute `Scope.Scope`, and this is the caller
+ *   that owns their lifetime for the whole reconcile.
+ * ⛔ WRITE-ONCE — see this file's own header. A bring-up already ran; this branch never spawns
+ *   `talosctl kubeconfig` or writes to the vault again.
+ * ⛔ GATED ON `credentialGeneration`, NOT JUST `output !== undefined` (C1 fix, LAND red team,
+ *   belt-and-suspenders alongside the `read` fix above) — `output`'s own type still allows a
+ *   defined-but-empty value (state persisted by a pre-fix build's `emptyAttrs()`, or any future
+ *   caller that hands this function a stale row). Treat that exactly like `undefined` — mint and
+ *   write once — rather than take the confirm-only branch and fail trying to read back a key that
+ *   was never actually written.
+ */
+export const reconcileKubeconfig = (
+  props: KubeconfigProps,
+  output: KubeconfigAttributes | undefined,
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const key = props.kubeconfigKey ?? DEFAULT_KUBECONFIG_KEY;
+
+      if (output !== undefined && output.credentialGeneration !== '') {
+        const raw = yield* readKvValue(props.target.mount, key, ['kubeconfig', 'config']);
+        const meta = buildAttrs(raw, props);
+        if (meta === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${props.target.mount}/${key}: vault content no longer parses as a kubeconfig for ` +
+                `context ${props.context}. Read back rather than trusting the write once.`,
+            ),
+          );
+        }
+        return meta;
+      }
+
+      const credential = yield* mintTalosconfig(props.target);
+      const { path: outPath } = yield* reservedTempPath(
+        `${props.target.cluster}-${props.node}-kubeconfig-out`,
       );
-    }
-    return meta;
-  });
+      yield* talosctl(
+        ['kubeconfig', outPath, '--merge=false', '--force', '--force-context-name', props.context],
+        { nodes: [props.node], talosconfigPath: credential.talosconfigPath },
+      );
+      const raw = yield* Effect.tryPromise({
+        catch: (cause) => new Error(`${outPath}: reading generated kubeconfig: ${String(cause)}`),
+        try: () => Bun.file(outPath).text(),
+      });
+      if (raw.trim() === '') {
+        return yield* Effect.die(
+          new Error(
+            `${props.node}: talosctl kubeconfig returned no error but wrote an empty file. Read ` +
+              'back rather than trusting the exit code alone.',
+          ),
+        );
+      }
+      // ⚠️ REASONED, not measured: talosctl's own writer likely already uses 0600 like most Go
+      //   credential writers, but this chmods defensively regardless — same posture as
+      //   credentials.ts's mintKvTempFile.
+      yield* Effect.try({
+        catch: (cause) => new Error(`${outPath}: chmod 0600: ${String(cause)}`),
+        try: () => chmodSync(outPath, 0o600),
+      });
+      const meta = buildAttrs(raw, props);
+      if (meta === undefined) {
+        return yield* Effect.die(
+          new Error(
+            `${props.node}: talosctl kubeconfig wrote a file that does not parse for context ` +
+              `${props.context}.`,
+          ),
+        );
+      }
+      yield* writeKvValue(props.target.mount, key, 'kubeconfig', raw);
+      return meta;
+    }),
+  );
 
 const handlers = {
   delete: () => Effect.void,
@@ -160,10 +234,16 @@ const handlers = {
   }: {
     news: Input<KubeconfigProps>;
     output: KubeconfigAttributes | undefined;
-  }) => diff(news, output),
+  }) => diffKubeconfig(news, output),
   list: () => Effect.succeed([]),
-  read: ({ olds }: { olds: KubeconfigProps }) => read(olds),
-  reconcile: ({ news }: { news: KubeconfigProps }) => reconcile(news),
+  read: ({ olds }: { olds: KubeconfigProps }) => readKubeconfig(olds),
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: KubeconfigProps;
+    output: KubeconfigAttributes | undefined;
+  }) => reconcileKubeconfig(news, output),
 };
 
 export const TalosKubeconfigProvider = () =>

package/src/talos/machine-config-fixtures.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared fixtures for talos-machine-config.test.ts and machine-config-poll.test.ts — split out
+ * so neither test file needs to duplicate the fake `bao`/`talosctl` dispatcher (2026-09-26, K-A3).
+ *
+ * ⚠️ FIXTURES ONLY. `CONFIG_TEXT` is a plain marker string, never anything resembling a real
+ *   Talos machine config, CA key or bootstrap token. No provider imports this file.
+ */
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import type { MachineConfigProps } from './talos-machine-config.ts';
+import { configDigest } from './values.ts';
+
+export const CONFIG_TEXT = 'machine:\n  type: worker\n';
+export const PIN = configDigest(CONFIG_TEXT);
+export const TARGET = { cluster: 'c1', mount: 'talos-c1' };
+export const FAST_POLL = {
+  immediate: { intervalMs: 0, maxAttempts: 3 },
+  rebootish: { intervalMs: 0, maxAttempts: 4 },
+};
+
+export const props = (overrides: Partial<MachineConfigProps> = {}): MachineConfigProps => ({
+  configDigest: PIN,
+  configKey: 'nodes/10001',
+  node: '198.51.100.10',
+  target: TARGET,
+  ...overrides,
+});
+
+/** Shape REASONED from talosctl's `get machineconfig -o yaml` — see values.ts's own header. */
+export const wrapperFor = (specText: string, version = '1') =>
+  `node: 198.51.100.10\nmetadata:\n  version: "${version}"\nspec: "${specText.replace(/\n/g, '\\n')}"\n`;
+
+/** Routes fake `bao kv get` (config + talosconfig keys) and `talosctl` calls in one place. */
+export const dispatcher = (opts: {
+  configText?: string;
+  liveWrapper?: () => { stdout?: string; exitCode?: number };
+  applyExitCode?: number;
+  /**
+   * Controls the fix-first #1 maintenance-mode probe (`talosctl version --insecure`), reached only
+   * when the authenticated `get machineconfig` above fails. Defaults to `false` so a bare failing
+   * `liveWrapper` (most tests) still exercises the "both reads fail → propagate" path rather than
+   * silently succeeding at the probe.
+   */
+  maintenanceReachable?: boolean;
+}) => {
+  const configText = opts.configText ?? CONFIG_TEXT;
+  return (call: FakeCall) => {
+    if (call.command === 'bao') {
+      const key = call.args[3] ?? '';
+      if (key.endsWith('/talosconfig')) {
+        return {
+          stdout: JSON.stringify({ data: { data: { talosconfig: 'fake-talosconfig-body' } } }),
+        };
+      }
+      return { stdout: JSON.stringify({ data: { data: { config: configText } } }) };
+    }
+    if (call.command === 'talosctl') {
+      if (call.args[0] === 'apply-config') return { exitCode: opts.applyExitCode ?? 0 };
+      if (call.args[0] === 'version')
+        return (opts.maintenanceReachable ?? false)
+          ? { stdout: 'Client: v1.13.10\nServer: v1.13.10\n' }
+          : { exitCode: 1, stderr: 'dial tcp: connection refused' };
+      if (call.args[0] === 'get')
+        return opts.liveWrapper?.() ?? { stdout: wrapperFor(CONFIG_TEXT) };
+    }
+    throw new Error(`dispatcher: unexpected call ${JSON.stringify(call)}`);
+  };
+};
+
+export 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),
+    ),
+  );
+
+/** `Data.TaggedError` stamps `_tag`, not `.message` — see talos-errors.ts. */
+export const hasTag = (tag: string) => (error: unknown) =>
+  (error as { _tag?: string } | null)?._tag === tag;

package/src/talos/machine-config-poll.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Bounded-poll-per-mode acceptance tests from docs/plans/2026-09-26-talos-stack-first-boot.md's
+ * "Converged" section — exercised through `reconcileMachineConfig` with `FAST_POLL` (a test-only
+ * seam, see machine-config-poll.ts's own header) so the ~10s/~2m production caps never run here.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  CONFIG_TEXT,
+  FAST_POLL,
+  dispatcher,
+  hasTag,
+  props,
+  run,
+  wrapperFor,
+} from './machine-config-fixtures.ts';
+import type { ApplyMode } from './resource.ts';
+import { reconcileMachineConfig } from './talos-machine-config.ts';
+
+describe('reconcileMachineConfig — bounded poll per mode', () => {
+  const rebootish: ApplyMode = 'reboot';
+  const immediate: ApplyMode = 'no-reboot';
+
+  it("no-reboot converges via a single successful read-back ('read-back')", async () => {
+    const out = await run(
+      reconcileMachineConfig(props({ mode: immediate }), undefined, FAST_POLL),
+      dispatcher({}),
+    );
+    assert.equal(out.converged, 'read-back');
+  });
+
+  it("reboot/auto tolerate a transient miss then converge ('accepted')", async () => {
+    let attempt = 0;
+    const out = await run(
+      reconcileMachineConfig(props({ mode: rebootish }), undefined, FAST_POLL),
+      dispatcher({
+        liveWrapper: () => {
+          attempt += 1;
+          return attempt < 2
+            ? { exitCode: 1, stderr: 'node rebooting' }
+            : { stdout: wrapperFor(CONFIG_TEXT) };
+        },
+      }),
+    );
+    assert.equal(out.converged, 'accepted');
+  });
+
+  it('raises TalosConvergenceTimeout, never a silent pass, when the cap expires', async () => {
+    await assert.rejects(
+      run(
+        reconcileMachineConfig(props({ mode: rebootish }), undefined, FAST_POLL),
+        dispatcher({ liveWrapper: () => ({ exitCode: 1, stderr: 'still unreachable' }) }),
+      ),
+      hasTag('TalosConvergenceTimeout'),
+    );
+  });
+});

package/src/talos/machine-config-poll.ts

@@ -0,0 +1,82 @@
+/**
+ * Post-apply convergence for `Talos.MachineConfig` — split out of talos-machine-config.ts
+ * (2026-09-26, K-A3) once the bounded-poll logic needed its own header. See
+ * docs/plans/2026-09-26-talos-stack-first-boot.md, "Converged" and "Bootstrap" sections.
+ *
+ * ⛔ NO SILENT `converged: false` HERE. A single attempt's own transport failure is swallowed
+ *   ONLY inside the bounded loop below — a rebooting node's API is legitimately unreachable for a
+ *   while — but the loop AS A WHOLE never swallows: running out of attempts always raises
+ *   `TalosConvergenceTimeout`, never a quiet `false`. That distinction is read()'s job, not
+ *   reconcile's — see talos-machine-config.ts.
+ * ⚠️ SHORT INTERVALS, A LOW CAP, NEVER ONE LONG SLEEP — the house timeout rule, and the specific
+ *   reason talosctl's own `health` gate has a 20-minute `--wait-timeout`: a single blocking wait
+ *   that long would hide whether THIS process is still alive from anything watching it.
+ */
+import * as Effect from 'effect/Effect';
+import type { ApplyMode } from './resource.ts';
+import { TalosConvergenceTimeout } from './talos-errors.ts';
+
+/**
+ * Modes whose apply can trigger a full install + reboot. REASONED, Talos v1.13 CLI reference.
+ * ⛔ `'staged'` is deliberately absent — resource.ts's own header explains why (fix-first #2).
+ */
+const isRebootish = (mode: ApplyMode) => mode === 'reboot' || mode === 'auto';
+
+/**
+ * ★ TWO POLICIES, ONE PER MODE CLASS — REASONED, no live cluster to time this against yet.
+ *   `no-reboot` never drops the API, so a handful of quick retries covers only ordinary
+ *   config-propagation lag. `reboot`/`auto` can drop the API for a full boot cycle, so the cap is
+ *   longer and the interval coarser. Both stay well inside the house rule above.
+ */
+export type PollPolicy = { readonly intervalMs: number; readonly maxAttempts: number };
+
+const POLICY: { readonly immediate: PollPolicy; readonly rebootish: PollPolicy } = {
+  immediate: { intervalMs: 2_000, maxAttempts: 5 }, // ~10s cap
+  rebootish: { intervalMs: 5_000, maxAttempts: 24 }, // ~2m cap
+};
+
+/**
+ * Run `check` until it reports `true` or `maxAttempts` is spent, sleeping `intervalMs` between
+ * attempts. A per-attempt failure counts as "not yet" and does not end the loop early.
+ */
+const pollUntilMatch = <E, R>(
+  check: Effect.Effect<boolean, E, R>,
+  policy: { readonly intervalMs: number; readonly maxAttempts: number },
+): Effect.Effect<boolean, never, R> =>
+  Effect.gen(function* () {
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+      const matched = yield* check.pipe(Effect.orElseSucceed(() => false));
+      if (matched) return true;
+      if (attempt < policy.maxAttempts) yield* Effect.sleep(policy.intervalMs);
+    }
+    return false;
+  });
+
+/**
+ * Confirm convergence per `mode`'s policy, or fail with `TalosConvergenceTimeout`.
+ *
+ * Returns which CLAIM was proven, never a boolean — `'read-back'` for the immediate policy
+ * (no-reboot), `'accepted'` for the reboot-tolerant one (reboot/auto): state records which kind of
+ * confirmation actually happened, per the design doc's `converged` field.
+ *
+ * ⚠️ `policies` IS A TEST SEAM, NOT A PROP. `talos-machine-config.ts` never passes it, so
+ *   production always runs the REASONED defaults above; tests pass tiny intervals so a bounded
+ *   poll test finishes in milliseconds instead of the real ~10s/~2m caps.
+ */
+export const confirmConverged = <E, R>(
+  node: string,
+  mode: ApplyMode,
+  check: Effect.Effect<boolean, E, R>,
+  policies: { readonly immediate: PollPolicy; readonly rebootish: PollPolicy } = POLICY,
+): Effect.Effect<'read-back' | 'accepted', TalosConvergenceTimeout, R> =>
+  Effect.gen(function* () {
+    const rebootish = isRebootish(mode);
+    const policy = rebootish ? policies.rebootish : policies.immediate;
+    const matched = yield* pollUntilMatch(check, policy);
+    if (!matched) {
+      return yield* Effect.fail(
+        new TalosConvergenceTimeout({ attempts: policy.maxAttempts, mode, node }),
+      );
+    }
+    return rebootish ? 'accepted' : 'read-back';
+  });