c8ctl-plugin-nano 1.44.4 → 1.44.6

package/README.md

@@ -262,6 +262,19 @@ specialisation.
 > (capability-declared) enrolment path. Use `--auto-scope <process-id | prefix>`
 > to narrow the blast radius to one app/network.
 
+> **Dual-stack / IPv6-first engine hosts.** The engine client races IPv4 and IPv6
+> (Happy-Eyeballs, RFC 8305) at connect time, so a worker whose engine host
+> resolves to an **unreachable IPv6 address first** — common with macOS mDNS
+> (`merlin.local → fe80::… (dead) → 192.168.x.x`), a stray/misordered `AAAA`, or
+> an IPv6-advertised host — transparently falls back to IPv4 instead of failing
+> the activation / `--auto` engine read (`fetch failed` / `write EPIPE` /
+> `UND_ERR_CONNECT_TIMEOUT`). Without this, the `--auto` autoscaler would read
+> `0` job types and **silently scale the fleet to zero** (workers vanish from the
+> Nano console) even though `curl`/`fetch` reach the same host fine
+> (jwulf/c8ctl-plugin-nano#139). No configuration is needed; if you still want to
+> pin a family you can set `NODE_OPTIONS=--dns-result-order=ipv4first` or point
+> the engine URL at the IPv4 literal.
+
 
 The optional `--name` sets **this worker's name** — the `workerName` it
 registers under at the broker (`‹name›:‹jobType›`) and how it shows up in

package/c8ctl-plugin.js

@@ -51,6 +51,7 @@ import {
   unwatchFile,
 } from 'node:fs';
 import { createConnection, createServer } from 'node:net';
+import * as nodeNet from 'node:net';
 import { lookup as dnsLookup } from 'node:dns/promises';
 import { randomUUID, createHash, randomBytes } from 'node:crypto';
 import { homedir, platform as osPlatform, devNull, tmpdir, hostname } from 'node:os';
@@ -6045,6 +6046,58 @@ function buildActivityPayload({ pid, updatedAt, jobs, engine, agentic }) {
   };
 }
 
+/**
+ * Enable Happy-Eyeballs (RFC 8305) dual-stack connect for the engine client so a
+ * worker whose engine host resolves IPv6-first with an *unreachable* v6 address
+ * (macOS mDNS `fe80::` link-local, a stray/misordered AAAA, an IPv6-advertised
+ * host) transparently races and falls back to IPv4 — matching `curl`/`fetch` —
+ * instead of connecting to the dead address and failing the activation / `--auto`
+ * engine read with `fetch failed` / `write EPIPE` / `UND_ERR_CONNECT_TIMEOUT`
+ * (jwulf/c8ctl-plugin-nano#139).
+ *
+ * We set Node's PROCESS-WIDE `net` default rather than an instance option so the
+ * fix covers the *class*, not one call site: BOTH transports the worker harness
+ * uses inherit it — the `@camunda8` SDK client's `activateJobs` (its undici
+ * dispatcher connects via `net`) AND the raw-`fetch` `--auto` reconcile / initial
+ * engine reads. Node ≥20 already defaults this on, but older runtimes — and any
+ * build where the client's dispatcher inherits a `false` default — leave it off;
+ * the reporter's repro shows the failing "SDK default path" is exactly
+ * `setDefaultAutoSelectFamily(false)`, and asserting `true` here is what fixes it.
+ * The attempt timeout bounds the per-address race so a dead `fe80::` yields to
+ * IPv4 quickly (RFC 8305 default of 250ms) instead of stalling the connect.
+ *
+ * Fail-open and idempotent: a runtime without the API (or any throw) is swallowed
+ * so Happy-Eyeballs — an optimisation — can never block a worker from starting.
+ *
+ * @param {{ net?: object, attemptTimeoutMs?: number }} [opts] injection seam for tests
+ * @returns {boolean} true if the net default was (re)asserted to Happy-Eyeballs
+ */
+function enableEngineHappyEyeballs(opts = {}) {
+  try {
+    // Destructure INSIDE the try so a non-object arg (e.g. `null`) fails open
+    // like any other throw rather than blowing up before the guard.
+    const { net = nodeNet, attemptTimeoutMs = 250 } = opts || {};
+    if (net && typeof net.setDefaultAutoSelectFamily === 'function') {
+      net.setDefaultAutoSelectFamily(true);
+      // The attempt timeout is an optional refinement: once the primary family
+      // default is asserted the contract is satisfied, so a throw here must not
+      // retract our `true`. Swallow it independently.
+      try {
+        if (typeof net.setDefaultAutoSelectFamilyAttemptTimeout === 'function'
+            && Number.isFinite(attemptTimeoutMs) && attemptTimeoutMs > 0) {
+          net.setDefaultAutoSelectFamilyAttemptTimeout(attemptTimeoutMs);
+        }
+      } catch {
+        // Fail-open on the optional timeout setter; the family default still holds.
+      }
+      return true;
+    }
+  } catch {
+    // Fail-open: Happy-Eyeballs is a connectivity optimisation, never a start gate.
+  }
+  return false;
+}
+
 /**
  * work — turn a hire profile into live Nano job workers (one per job-type in
  * the rank×capability matrix) and poll for work in the foreground until Ctrl-C.
@@ -6279,6 +6332,12 @@ async function workAgent(req, flags) {
     logger.error('--auto-scope requires --auto (it narrows the engine-read agent job types).');
     process.exit(1);
   }
+  // Enable Happy-Eyeballs (RFC 8305) at the socket layer BEFORE the SDK client
+  // or any engine read is created, so a worker whose engine host resolves
+  // IPv6-first with a dead v6 address falls back to IPv4 instead of silently
+  // scaling the fleet to zero (jwulf/c8ctl-plugin-nano#139). Process-wide, so it
+  // covers both the SDK's activateJobs and the raw-fetch --auto engine reads.
+  enableEngineHappyEyeballs();
   const camunda = globalThis.c8ctl.createClient();
 
   // Broker REST endpoint for live linked-resource prompts (issue #63) and the
@@ -11612,6 +11671,7 @@ export {
   serviceTaskHasAgentHeader,
   readDeployedAgentJobTypes,
   resolveAutoJobTypes,
+  enableEngineHappyEyeballs,
   workAgent,
   derivePollTimeoutMs,
   AGENT_TASK_NS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.44.4",
+  "version": "1.44.6",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -57,12 +57,12 @@
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.44.4",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.44.4",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.44.4",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.44.4",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.44.4",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.44.4",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.44.4"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.44.6",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.44.6",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.44.6",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.44.6",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.44.6",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.44.6",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.44.6"
   }
 }

package/work-relay.mjs

@@ -23,6 +23,8 @@
 // a duck-typed terminal handle, so it is unit-testable with a fake terminal and
 // a fake channel.
 
+import { transcript as agenticTranscript } from './agentic.mjs';
+
 /** Prefix for a per-job relay stream name. One stream carries a job's terminal. */
 export const RELAY_STREAM_PREFIX = 'job:';
 
@@ -40,6 +42,26 @@ export function relayStreamName(jobKey) {
   return `${RELAY_STREAM_PREFIX}${String(jobKey)}`;
 }
 
+/**
+ * The initial produce frame emitted on a relay stream the instant a session is
+ * created: a canonical `@nanobpm/agentic` lifecycle "open" transcript event.
+ *
+ * It carries no agent output — its sole job is to OPEN the `job:<jobKey>` stream
+ * immediately so the app's correlation registry links this worker→jobKey on
+ * session creation, INDEPENDENT of whether the agent later emits any transcript
+ * bytes. Without it, a quiet ACP agent (one that emits no mappable
+ * `session/update`) never produces a `job:` frame, so the app never correlates
+ * the job — it renders "—" in the cockpit with no drill-in, even though the job
+ * ran and completed (regression since #128 coupled correlation to transcript
+ * bytes). Newline-framed to match the transcript-chunk framing the ACP relay
+ * path uses, and derived through `encodeTranscriptEvent` (never hand-rolled) so
+ * the wire marker stays single-sourced in `@nanobpm/agentic`.
+ */
+export const RELAY_OPEN_CHUNK = `${agenticTranscript.encodeTranscriptEvent({
+  kind: 'lifecycle',
+  phase: 'open',
+})}\n`;
+
 /**
  * Resolve a role's terminal mode — whether the agent harness for this role gets
  * a full PTY or a plain pipe. Honors the vocab's per-role opt-in: a role may set
@@ -189,5 +211,11 @@ export function createRelaySession({ channel, jobKey, logger } = {}) {
     for (const detach of [...activeDetaches]) detach();
   };
 
+  // Open the stream the instant the session exists, so the app correlates
+  // worker→jobKey immediately — independent of any later agent transcript bytes
+  // (a quiet ACP agent emits none). Routed through the internal relay(), which
+  // already swallows sink errors, so opening the stream never fails the job.
+  relay(RELAY_OPEN_CHUNK);
+
   return { stream, relay, attachSteer, close };
 }