@homeflare/alchemy 0.48.0 → 0.49.0

package/src/cloudflare/saas-oidc.test.ts

@@ -0,0 +1,201 @@
+/**
+ * SaasOidcApplicationProvider against a fake Access API (fake-access.ts), its handlers called the
+ * way the engine calls them. Read, delete and adoption: saas-oidc-read.test.ts.
+ *
+ * ⛔ THE ASSERTIONS THAT MATTER MOST: a public PKCE client is created with
+ *   `allow_pkce_without_client_secret` and the `authorization_code_with_pkce` grant, and the client
+ *   secret — which the fake's create response DOES hand out, as the API does on POST — appears in
+ *   no attribute, no log line and no request body.
+ */
+import { afterEach, describe, expect, spyOn, test } from 'bun:test';
+import type { StackServices } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import { FAKE_CLIENT_SECRET, TEAM, fakeAccess } from './fake-access.ts';
+import { FAKE_ACCOUNT } from './fake-mesh.ts';
+import { providers } from './providers.ts';
+import { LIVE_OIDC, publicClient, reconcile, run, writes } from './saas-oidc-harness.ts';
+import { SaasOidcApplication } from './saas-oidc.ts';
+
+// ⛔ Compile-time: a stack's `providers` must be `Layer<…, never, StackServices>`. A provider with
+//   an open error channel leaks it here, and `bun run types` catches that.
+type Built = Layer.Success<ReturnType<typeof providers>>;
+const _stackShaped: Layer.Layer<Built, never, StackServices> = providers();
+void _stackShaped;
+
+const postBody = (fake: ReturnType<typeof fakeAccess>) =>
+  fake.seen.find((s) => s.method === 'POST')?.body as Record<string, unknown>;
+
+describe('SaasOidcApplication identity', () => {
+  test('the type id is the one the openbao state rows are keyed by', () => {
+    expect(SaasOidcApplication.Type).toBe('HomeFlare.Access.SaasOidcApplication');
+  });
+});
+
+describe('create', () => {
+  const debug = process.env['DISTILLED_DEBUG_HTTP'];
+  afterEach(() => {
+    if (debug === undefined) delete process.env['DISTILLED_DEBUG_HTTP'];
+    else process.env['DISTILLED_DEBUG_HTTP'] = debug;
+  });
+
+  test('a public client is sent as PKCE with no secret, and read back for its client id', async () => {
+    const fake = fakeAccess();
+    const spies = [spyOn(console, 'log'), spyOn(console, 'error'), spyOn(console, 'warn')];
+    const out = await run(fake, (p) => reconcile(p, publicClient()));
+    const logged = JSON.stringify(spies.map((spy) => spy.mock.calls));
+    for (const spy of spies) spy.mockRestore();
+    expect(postBody(fake)).toMatchObject({
+      type: 'saas',
+      name: 'Headlamp',
+      policies: ['policy-admin'],
+      saas_app: {
+        auth_type: 'oidc',
+        grant_types: ['authorization_code_with_pkce'],
+        allow_pkce_without_client_secret: true,
+        access_token_lifetime: '15m',
+      },
+    });
+    expect(writes(fake)).toEqual(['POST']);
+    expect(out).toMatchObject({ accountId: FAKE_ACCOUNT, teamDomain: TEAM, name: 'Headlamp' });
+    expect(out.issuer).toBe(`https://${TEAM}/cdn-cgi/access/sso/oidc/${out.clientId}`);
+    expect(out.jwksEndpoint).toBe(`${out.issuer}/jwks`);
+    // ⛔ The secret was in the create response. It is nowhere we control.
+    expect(JSON.stringify(out)).not.toContain(FAKE_CLIENT_SECRET);
+    expect(JSON.stringify(fake.seen)).not.toContain(FAKE_CLIENT_SECRET);
+    expect(logged).not.toContain(FAKE_CLIENT_SECRET);
+    expect(Object.keys(out)).not.toContain('clientSecret');
+  });
+
+  test('refuses while DISTILLED_DEBUG_HTTP is set, before any write', async () => {
+    process.env['DISTILLED_DEBUG_HTTP'] = '1';
+    const fake = fakeAccess();
+    // The SDK prints the name lookup's (secret-free) response while the variable is set.
+    const quiet = spyOn(console, 'error').mockImplementation(() => {});
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, publicClient())));
+    quiet.mockRestore();
+    expect(String(failure)).toContain('DISTILLED_DEBUG_HTTP');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('an invalid declaration fails before any request', async () => {
+    const fake = fakeAccess();
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, publicClient({ teamDomain: 'https://x.test' }))),
+    );
+    expect(String(failure)).toContain('teamDomain');
+    expect(fake.seen).toEqual([]);
+  });
+});
+
+describe('reconcile against a live app', () => {
+  test('makes zero writes when nothing drifted', async () => {
+    const fake = fakeAccess();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, publicClient());
+        return [created, yield* reconcile(p, publicClient(), created)] as const;
+      }),
+    );
+    expect(second).toEqual(first);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('a changed redirect URI is one PUT, and the client id survives', async () => {
+    const fake = fakeAccess();
+    const base = publicClient();
+    const changed = {
+      ...base,
+      saasApp: { ...base.saasApp, redirectUris: ['https://headlamp.example.test/new'] },
+    };
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, base);
+        return [created, yield* reconcile(p, changed, created)] as const;
+      }),
+    );
+    expect(writes(fake)).toEqual(['POST', 'PUT']);
+    expect(second.redirectUris).toEqual(['https://headlamp.example.test/new']);
+    expect(second.clientId).toBe(first.clientId);
+    expect(second.applicationId).toBe(first.applicationId);
+    expect(JSON.stringify(fake.seen)).not.toContain(FAKE_CLIENT_SECRET);
+  });
+
+  test('a reordered policy list is one PUT that carries the new order', async () => {
+    const fake = fakeAccess();
+    const base = publicClient({ policies: ['policy-a', 'policy-b'] });
+    const swapped = { ...base, policies: ['policy-b', 'policy-a'] };
+    const second = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const created = yield* reconcile(p, base);
+        return yield* reconcile(p, swapped, created);
+      }),
+    );
+    expect(second.applicationId).toBeDefined();
+    expect(writes(fake)).toEqual(['POST', 'PUT']);
+    expect(fake.seen.filter((s) => s.method === 'PUT')[0]?.body).toMatchObject({
+      policies: ['policy-b', 'policy-a'],
+    });
+    // The fake holds the new order, so the next read sees it in sync.
+    expect(fake.apps.get(second.applicationId)?.policies).toEqual(['policy-b', 'policy-a']);
+  });
+
+  test("a declared team that is not the app's team is refused before any write", async () => {
+    const fake = fakeAccess({ team: 'real.cloudflareaccess.com' });
+    const live = fake.seed({ name: 'Headlamp' });
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        reconcile(
+          p,
+          publicClient({ applicationId: live.id, teamDomain: 'other.cloudflareaccess.com' }),
+        ),
+      ),
+    );
+    expect(String(failure)).toContain('real.cloudflareaccess.com');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('an owned row whose app was deleted out of band never adopts a same-named app', async () => {
+    const fake = fakeAccess();
+    const made = await run(fake, (p) => reconcile(p, publicClient()));
+    fake.apps.delete(made.applicationId);
+    const impostor = fake.seed({
+      name: 'Headlamp',
+      policies: ['policy-admin'],
+      saas_app: LIVE_OIDC,
+    });
+    const before = fake.seen.length;
+    const out = await run(fake, (p) => reconcile(p, publicClient(), made));
+    // A fresh app is created; the same-named one is neither adopted nor written.
+    expect(out.applicationId).not.toBe(impostor.id);
+    expect(out.applicationId).not.toBe(made.applicationId);
+    expect(
+      fake.seen
+        .slice(before)
+        .filter((r) => r.method !== 'GET')
+        .map((r) => r.method),
+    ).toEqual(['POST']);
+    expect(fake.apps.get(impostor.id)?.saas_app?.['client_id']).toBe(
+      impostor.saas_app?.['client_id'],
+    );
+  });
+
+  test('an id that is not a saas app is refused, never rewritten', async () => {
+    const fake = fakeAccess();
+    const selfHosted = fake.seed({ name: 'Headlamp', type: 'self_hosted' });
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, publicClient({ applicationId: selfHosted.id }))),
+    );
+    expect(String(failure)).toContain('not "saas"');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('two saas apps with the declared name are refused, not guessed between', async () => {
+    const fake = fakeAccess();
+    fake.seed({ name: 'Headlamp' });
+    fake.seed({ name: 'Headlamp' });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, publicClient())));
+    expect(String(failure)).toContain('matches 2 live apps');
+    expect(writes(fake)).toEqual([]);
+  });
+});

package/src/cloudflare/saas-oidc.ts

@@ -0,0 +1,107 @@
+/**
+ * `HomeFlare.Access.SaasOidcApplication` — a Cloudflare Access SaaS application that makes Access an
+ * OIDC identity provider for one relying party (OpenBao's JWT/OIDC auth, Headlamp, a Kubernetes
+ * API server). Usage and the secret rules: docs/saas-oidc.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Access.Application`. Alchemy beta.81's Application has
+ *   no `saas_app` field (its source mentions `saas` only as a type and in two comments), and
+ *   `@distilled.cloud/cloudflare` rc.13 decodes a saas app's GET and create response WITHOUT it, so
+ *   the client id cannot be read back through either. See saas-oidc-api.ts.
+ *
+ * ⛔ THE TYPE ID IS A STATE KEY, AND THIS ONE WAS MOVED, NOT RENAMED. It is the string the
+ *   homeflare-openbao stack's live `OpenBaoOidcSaas` row was written under. A different string would
+ *   make the next plan see a new resource and an orphaned one: a second OIDC app, with a new
+ *   client id and `aud`, and a delete of the live one unless it were retained. `tests` pin it.
+ *
+ * ★ `retain` BY DEFAULT, like every kit resource whose deletion breaks its consumers: deleting the
+ *   app deletes the client id every relying party is configured with. The openbao declaration
+ *   already pipes `RemovalPolicy.retain()`; `delete` stays fully implemented for a declaration
+ *   that opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/http/HttpClient';
+import type { Providers } from './providers.ts';
+import { deleteSaasOidc, readSaasOidc, reconcileSaasOidc } from './saas-oidc-lifecycle.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-form.ts';
+
+export interface SaasOidcApplication extends Resource<
+  'HomeFlare.Access.SaasOidcApplication',
+  SaasOidcApplicationProps,
+  SaasOidcApplicationAttributes,
+  never,
+  Providers
+> {}
+
+export const SaasOidcApplication: ResourceClass<SaasOidcApplication> =
+  Resource<SaasOidcApplication>('HomeFlare.Access.SaasOidcApplication', {
+    defaultRemovalPolicy: 'retain',
+  });
+
+const accountId = Effect.gen(function* () {
+  const resolved = yield* yield* Cloudflare.CloudflareEnvironment;
+  return resolved.accountId;
+});
+
+/**
+ * ★ `Provider.effect`, CAPTURING THE THREE SERVICES AT BUILD, as MeshNodeProvider does
+ *   (mesh-node.ts): correct whether or not the stack also merges `Cloudflare.providers()`.
+ */
+export const SaasOidcApplicationProvider = () =>
+  Provider.effect(
+    SaasOidcApplication,
+    Effect.gen(function* () {
+      const services = Context.make(
+        Cloudflare.CloudflareEnvironment,
+        yield* Cloudflare.CloudflareEnvironment,
+      ).pipe(
+        Context.add(Credentials, yield* Credentials),
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      // ★ Only the three captured services are provided; `createPhysicalName` still takes
+      //   InstanceId, Stack and Stage from the engine at call time, as in every Alchemy provider.
+      const run = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        Effect.provideContext(effect, services);
+
+      return SaasOidcApplication.Provider.of({
+        /**
+         * ★ THE ISSUER AND EVERY ENDPOINT ARE STABLE. They depend only on the team domain and the
+         *   client id, and `checkTeam` refuses any team other than the app's own host, so no update
+         *   of this app can move them. Alchemy's plan (Plan.ts `withStables`, beta.81) keeps ONLY
+         *   the listed attributes resolved for consumers of an updated resource; without them, a
+         *   redirect-URI change would leave `app.issuer` unresolved and re-plan every consumer
+         *   (the Talos KubeAuthenticationConfig, so a kube-apiserver restart on each node).
+         * ⚠️ `teamDomain` is NOT listed: state written by the openbao copy has no such attribute,
+         *   so a consumer would read `undefined` on the first plan after the move.
+         */
+        stables: [
+          'applicationId',
+          'aud',
+          'clientId',
+          'accountId',
+          'issuer',
+          'authorizationEndpoint',
+          'tokenEndpoint',
+          'jwksEndpoint',
+          'userinfoEndpoint',
+          'configurationEndpoint',
+        ],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Access.Application` already lists
+         *   every Access application in the account for `alchemy unsafe nuke` (its `list`, saas
+         *   apps included); a second listing here would make nuke delete each app twice.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        read: ({ id, olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readSaasOidc(account, id, olds, output))),
+        reconcile: ({ id, news, output }) =>
+          run(Effect.flatMap(accountId, (account) => reconcileSaasOidc(account, id, news, output))),
+        delete: ({ output }) => run(deleteSaasOidc(output)),
+      });
+    }),
+  );

package/src/talos/cluster-adapter-errors.ts

@@ -155,7 +155,8 @@ export class TalosClusterIdentityTimeout extends Data.TaggedError('TalosClusterI
   override get message(): string {
     return (
       `talos-openbao cluster '${this.cluster}': no answer to the kube-system uid read within ` +
-      `${this.seconds}s. Refused (failed closed) rather than waiting on a silent apiserver.`
+      `${this.seconds}s (the identity read's own deadline, inside the 10 s connect deadline). ` +
+      'Refused (failed closed) rather than waiting on a silent apiserver.'
     );
   }
 }

package/src/talos/cluster-adapter-move.test.ts

@@ -97,6 +97,8 @@ test('a silent apiserver fails closed with TalosClusterIdentityTimeout', async (
       Effect.runPromise(Effect.provideService(read, spawn, fakeSpawner(vault))),
     );
     expect(message).toContain('TalosClusterIdentityTimeout');
+    // The text names the identity read's own deadline inside the 10 s connect deadline.
+    expect(message).toContain("the identity read's own deadline, inside the 10 s connect deadline");
   } finally {
     api.restore();
   }

package/src/talos/cluster-adapter.ts

@@ -33,7 +33,8 @@
  *   (`TalosClusterMoved`); a move is a NEW identity resource per physical cluster, so the old
  *   rows keep their old uid and their cleanup reaches only the old cluster.
  * ⛔ ONE 10 s DEADLINE covers the vault read AND the uid GET (`withConnectDeadline`): a hung `bao`
- *   or silent apiserver fails with `TalosOpenBaoConnectTimeout` and the `bao` child is killed.
+ *   fails with `TalosOpenBaoConnectTimeout` and the `bao` child is killed. The uid GET has its own
+ *   5 s deadline inside it, so a silent apiserver fails first with `TalosClusterIdentityTimeout`.
  *   ⚠️ The in-flight HTTPS GET is NOT aborted: upstream `readObject` takes no signal
  *   (`internal/client.ts:75`), so the socket lives until the OS gives up. Left for the upstream ask.
  *

package/src/talos/mint-temp-file.test.ts

@@ -0,0 +1,44 @@
+/**
+ * `mintKvTempFile` when the write fails AFTER the exclusive 0600 create (disk full): the release
+ * is registered only once the acquire step succeeds, so the file must be removed inside the step.
+ * Fails on 0.48.0, which left the partial file behind.
+ */
+import * as fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { expect, spyOn, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { mintKvTempFile } from './mint-temp-file.ts';
+
+const leftovers = (label: string) =>
+  fs.readdirSync(tmpdir()).filter((name) => name.startsWith(`hf-talos-${label}-`));
+
+test('a write that fails after the exclusive create leaves no temp file behind', async () => {
+  const label = `write-fail-${process.pid}`;
+  // A non-string body makes writeFileSync throw after openSync already created the file: a real
+  // failure on the real code path, with no stub of node:fs.
+  const failure = await Effect.runPromise(
+    Effect.flip(Effect.scoped(mintKvTempFile(42 as unknown as string, label))),
+  );
+  expect(failure.message).toContain(`writing ${label} temp file`);
+  expect(leftovers(label)).toEqual([]);
+});
+
+test('a close that fails after a good write leaves no temp file behind', async () => {
+  const label = `close-fail-${process.pid}`;
+  const realClose = fs.closeSync;
+  // EIO/EDQUOT surface at close(2): close for real (no leaked fd), then report the failure.
+  const spy = spyOn(fs, 'closeSync').mockImplementation((fd: number) => {
+    realClose(fd);
+    throw new Error('EIO: simulated close failure');
+  });
+  try {
+    const failure = await Effect.runPromise(
+      Effect.flip(Effect.scoped(mintKvTempFile('credential\n', label))),
+    );
+    expect(failure.message).toContain('EIO: simulated close failure');
+    expect(spy).toHaveBeenCalled();
+  } finally {
+    spy.mockRestore();
+  }
+  expect(leftovers(label)).toEqual([]);
+});

package/src/talos/mint-temp-file.ts

@@ -3,7 +3,7 @@
  * credentials.ts (2026-10-06, red team PR 355) once the Node-runtime fix pushed that file past the
  * 250-line cap; the split mirrors credentials-write.ts, which was split out for its own header.
  */
-import { closeSync, openSync, writeFileSync } from 'node:fs';
+import { closeSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
@@ -39,10 +39,22 @@ export const mintKvTempFile = (
       Effect.try({
         try: () => {
           const fd = openSync(path, 'wx', 0o600);
+          // ⛔ The release below registers only after this step succeeds, so ANY failure here (a
+          //   disk-full write, or a close that errors: EIO/EDQUOT surface at close on a quota'd
+          //   tmpdir) would leave the 0600 file, possibly holding part of the credential, behind.
           try {
-            writeFileSync(fd, raw);
-          } finally {
-            closeSync(fd);
+            try {
+              writeFileSync(fd, raw);
+            } finally {
+              closeSync(fd);
+            }
+          } catch (cause) {
+            try {
+              unlinkSync(path);
+            } catch {
+              // nothing more to remove
+            }
+            throw cause;
           }
         },
         catch: (cause) => new Error(`writing ${label} temp file: ${String(cause)}`),

package/src/talos/talosctl-probe-kill.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The version probe's deadline against a REAL hanging child: the claim in talosctl.ts that a timed-out
+ * probe kills the child (and its process group) is proved here with `process.kill(pid, 0)`, not with a
+ * spawner that never starts anything. The script lives in a private os.tmpdir() directory removed on
+ * every exit path, and sleeps 60 s so a surviving child is unmistakable.
+ */
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as NodeServices from '@effect/platform-node/NodeServices';
+import { trustBoundaryForTests } from './trust-boundary.seam.ts';
+import { TalosBinaryRefused, talosctl } from './talosctl.ts';
+
+const dir = mkdtempSync(join(tmpdir(), 'hf-probe-kill-'));
+chmodSync(dir, 0o755);
+trustBoundaryForTests(dir);
+afterAll(() => rmSync(dir, { force: true, recursive: true }));
+
+const pidFile = join(dir, 'pids');
+const script = join(dir, 'talosctl');
+// The shell and its `sleep` grandchild both record their pid: the grandchild only dies if the whole
+// process group is killed, not just the direct child.
+writeFileSync(script, `#!/bin/sh\nsleep 60 &\necho "$$ $!" > '${pidFile}'\nwait\n`, {
+  mode: 0o755,
+});
+chmodSync(script, 0o755);
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code !== 'ESRCH';
+  }
+};
+
+test('a probe that hangs is refused and its real child and process group are gone', async () => {
+  const outcome = await Effect.runPromise(
+    Effect.flip(
+      talosctl(['version'], {
+        binary: script,
+        talosconfigPath: 'unused.yaml',
+        versionProbeTimeout: '1 seconds',
+      }).pipe(Effect.provide(NodeServices.layer)),
+    ),
+  );
+  expect(outcome).toBeInstanceOf(TalosBinaryRefused);
+  const pids = readFileSync(pidFile, 'utf8').trim().split(' ').map(Number);
+  expect(pids).toHaveLength(2);
+  // SIGKILL follows SIGTERM after `forceKillAfter` (1 s), so allow it to land.
+  const deadline = Date.now() + 5000;
+  while (pids.some(alive) && Date.now() < deadline) await Bun.sleep(100);
+  expect(pids.map(alive)).toEqual([false, false]);
+});

package/src/talos/talosctl.test.ts

@@ -6,11 +6,17 @@ import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, expect, test } from 'bun:test';
+import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
 import { type FakeCall, fakeSpawner } from './fake-process.ts';
 import { trustBoundaryForTests } from './trust-boundary.seam.ts';
-import { TALOSCTL_BINARY_ENV, talosctl } from './talosctl.ts';
+import {
+  TALOSCTL_BINARY_ENV,
+  TalosBinaryRefused,
+  VERSION_PROBE_TIMEOUT,
+  talosctl,
+} from './talosctl.ts';
 
 // ⚠️ A real, vetted file in a private directory: the system `sh` or `bun` may be a symlink or live
 //   in a writable directory, which the vetting (correctly) refuses.
@@ -108,3 +114,50 @@ test('a default talosctl that is not on PATH is refused, never run by bare name'
     }),
   );
 });
+
+test('a version probe that never answers is refused with a typed error, not awaited forever', async () => {
+  await withEnv(fixture, async () => {
+    const started = Date.now();
+    const outcome = await Effect.runPromise(
+      Effect.flip(
+        Effect.provideService(
+          // The default is 10 s (asserted below); a short override keeps the suite fast.
+          talosctl(['version'], {
+            talosconfigPath: 'unused.yaml',
+            versionProbeTimeout: '2 seconds',
+          }),
+          ChildProcessSpawner.ChildProcessSpawner,
+          ChildProcessSpawner.make(() => Effect.never),
+        ),
+      ),
+    );
+    expect(outcome).toBeInstanceOf(TalosBinaryRefused);
+    expect(outcome.message).toContain('did not answer within');
+    expect(Date.now() - started).toBeLessThan(4000);
+  });
+});
+
+test('the probe deadline is overridable per call and still fails closed', async () => {
+  await withEnv(fixture, async () => {
+    const started = Date.now();
+    const outcome = await Effect.runPromise(
+      Effect.flip(
+        Effect.provideService(
+          talosctl(['version'], {
+            talosconfigPath: 'unused.yaml',
+            versionProbeTimeout: '1 seconds',
+          }),
+          ChildProcessSpawner.ChildProcessSpawner,
+          ChildProcessSpawner.make(() => Effect.never),
+        ),
+      ),
+    );
+    expect(outcome).toBeInstanceOf(TalosBinaryRefused);
+    expect(outcome.message).toContain('did not answer within 1s');
+    expect(Date.now() - started).toBeLessThan(5000);
+  });
+});
+
+test('the default probe deadline is 10 s', () => {
+  expect(Duration.toSeconds(VERSION_PROBE_TIMEOUT)).toBe(10);
+});

package/src/talos/talosctl.ts

@@ -78,6 +78,13 @@ export type TalosRunOptions = {
    * since insecure mode ignores the file's certs rather than requiring their absence.
    */
   readonly insecure?: boolean;
+  /**
+   * Deadline for the `version --client` probe of the binary; past it the binary is refused (fails
+   * closed, never skipped). A cold first run of the Go binary under CI load can exceed a tight
+   * limit, so a caller may raise it.
+   * @default {@link VERSION_PROBE_TIMEOUT} (10 s)
+   */
+  readonly versionProbeTimeout?: Duration.Input;
 };
 
 const capture = (binary: string, argv: readonly string[]) =>
@@ -117,6 +124,16 @@ const capture = (binary: string, argv: readonly string[]) =>
     );
   });
 
+/**
+ * ⛔ THE VERSION PROBE IS BOUNDED. `talosctl version --client` talks to no cluster and answers in
+ *   milliseconds, so a probe silent for this long is a hung or hostile binary: it is refused
+ *   (failed closed, typed) instead of parking the caller forever. Interrupting the scope kills the
+ *   child with its process group (proved against a real hanging child by talosctl-probe-kill.test.ts).
+ * ⚠️ 10 s, not 3 s: a cold first run of the Go binary under CI load can take seconds, and a
+ *   refusal there is a false alarm. Override per call with `TalosRunOptions.versionProbeTimeout`.
+ */
+export const VERSION_PROBE_TIMEOUT = Duration.seconds(10);
+
 /** ⚠️ EXACT TOKEN MATCH: `includes` would accept v1.14.20 for v1.14.2. */
 const reportsPinnedVersion = (stdout: string) =>
   stdout.split(/[^\w.+-]+/).includes(TALOSCTL_PINNED_VERSION);
@@ -125,8 +142,23 @@ const reportsPinnedVersion = (stdout: string) =>
  * ⛔ AN OVERRIDE MUST REPORT THE PINNED CLIENT VERSION (`version --client`, no talosconfig, so
  *   nothing secret reaches an untrusted binary before it is vetted).
  */
-const checkOverrideVersion = (binary: string, source: string) =>
+const checkOverrideVersion = (
+  binary: string,
+  source: string,
+  timeout: Duration.Input = VERSION_PROBE_TIMEOUT,
+) =>
   capture(binary, ['version', '--client']).pipe(
+    Effect.timeoutOrElse({
+      duration: timeout,
+      orElse: () =>
+        Effect.fail(
+          new TalosBinaryRefused(
+            'version --client',
+            `${source} did not answer within ${String(Duration.toSeconds(timeout))}s`,
+            binary,
+          ),
+        ),
+    }),
     Effect.flatMap((out) =>
       out.exitCode === 0 && reportsPinnedVersion(out.stdout)
         ? Effect.void
@@ -155,7 +187,7 @@ export const talosctl = (args: readonly string[], options: TalosRunOptions) =>
           : TALOSCTL_BINARY_ENV;
     // ⛔ Launch exactly the vetted canonical path, for the probe and the credentialed call alike.
     const binary = yield* checkBinaryPath(resolved, source);
-    yield* checkOverrideVersion(binary, source);
+    yield* checkOverrideVersion(binary, source, options.versionProbeTimeout);
     const argv = [
       ...args,
       '--talosconfig',