c8ctl-plugin-nano 1.44.5 → 1.44.7

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';
@@ -4567,6 +4568,15 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
     // One-time warning latch for the reserved escalate/filter policies so the
     // deferral is observable (not silent) but never spams a warning per request.
     let interimWarned = false;
+    // #137: count of canonical transcript chunks actually PUBLISHED to the relay's
+    // transcript-chunk seam, plus a one-time latch for the fallback floor. Some ACP
+    // agents (e.g. copilot 1.0.82 on some hosts) complete a turn without ever
+    // emitting a mappable `session/update`, so `emitTranscript` never fires and the
+    // cockpit drill-in would show an empty session. When the turn completes having
+    // published zero chunks, we synthesise ONE structured floor chunk so the
+    // drill-in shows the outcome instead of nothing (see `maybeEmitTranscriptFloor`).
+    let transcriptChunksPublished = 0;
+    let floorEmitted = false;
 
     // Live "spy" tee (--stream), line-buffered, mirroring the other paths.
     // Separate line buffers per lane (stdout-human vs stderr) so a partial line
@@ -4637,6 +4647,13 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       if (idleMon) idleMon.stop();
       if (settleTimer) { clearTimeout(settleTimer); settleTimer = null; }
       if (detachSteer) { try { detachSteer(); } catch { /* best effort */ } detachSteer = null; }
+      // #137: a turn that completed but produced no mappable session/update gets a
+      // synthesised structured floor so the cockpit drill-in isn't empty. Only for
+      // a resolved turn (`promptResolved`) — a handshake/spawn failure has nothing
+      // to floor and its error is surfaced in the result envelope. Best-effort and
+      // guarded, so it can never turn a settle into a throw. Runs before the tee is
+      // flushed so a --stream watcher sees the floored line too.
+      if (promptResolved) { try { maybeEmitTranscriptFloor(); } catch { /* floor best-effort */ } }
       if (teeSink) { tee('', true); teeErr('', true); }
       // Reap the child if it is still alive (turn resolved but agent lingering).
       try { if (child && childClosed === null) killTree(child); } catch { /* best effort */ }
@@ -4774,6 +4791,7 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
         let published = false;
         try { relayTap.relayTranscriptChunk(chunk); published = true; } catch { /* relay best-effort */ }
         if (published) {
+          transcriptChunksPublished++;
           // Mirror the human text locally (spy tee + captured stdout) so the
           // result envelope and --stream spy are unchanged — without re-emitting
           // raw text onto the relay lane, which now carries the canonical chunk.
@@ -4786,6 +4804,76 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       emitHuman(describeUpdate(update));
     };
 
+    // #137: build the human-readable text for a fallback transcript FLOOR — used
+    // only when a turn completed having produced no mappable session/update, so
+    // the cockpit drill-in shows the run's OUTCOME instead of an empty session.
+    // Prefer the agent's own structured result (from $AGENT_RESULT_FILE: summary,
+    // status, pr), then its stderr diagnostics, then a fixed explanatory note.
+    const buildFloorText = () => {
+      const resultPath = env && typeof env === 'object' ? env[AGENT_RESULT_FILE_ENV] : null;
+      const res = readAgentResultFile(resultPath);
+      if (res && typeof res === 'object') {
+        const parts = [];
+        if (typeof res.summary === 'string' && res.summary.trim()) parts.push(res.summary.trim());
+        if (typeof res.status === 'string' && res.status.trim()) parts.push(`(status: ${res.status.trim()})`);
+        if (typeof res.pr === 'string' && res.pr.trim()) parts.push(`PR: ${res.pr.trim()}`);
+        else if (res.pr && typeof res.pr === 'object' && typeof res.pr.url === 'string' && res.pr.url.trim()) parts.push(`PR: ${res.pr.url.trim()}`);
+        if (parts.length) return parts.join(' ');
+      }
+      const diag = joinCapped(stderrChunks).trim();
+      if (diag) {
+        // Surface the tail of the agent's stderr (its own diagnostics) as the
+        // floor — capped so a chatty agent can't blow up a single transcript card.
+        const FLOOR_DIAG_CAP = 2_000;
+        const tail = diag.length > FLOOR_DIAG_CAP ? `…${diag.slice(diag.length - FLOOR_DIAG_CAP)}` : diag;
+        return `Agent published no structured/canonical transcript content. Diagnostics:\n${tail}`;
+      }
+      return 'Agent completed the turn but published no structured/canonical transcript content, so no transcript messages were produced.';
+    };
+
+    // #137: synthesise ONE structured transcript-chunk FLOOR when a completed turn
+    // published zero canonical chunks. The floor rides the SAME canonical bridge
+    // (an `agent_message_chunk` run through `acpUpdateToTranscriptChunk`) so the
+    // cockpit renders a real assistant-message card — never a hand-rolled envelope
+    // — and honours the acceptance's "structured/raw transcript floor" so the
+    // drill-in shows something useful rather than an empty session. Idempotent
+    // (one-time latch), inert unless the relay exposes the transcript-chunk seam,
+    // and skipped entirely when any real chunk already reached the lane.
+    const maybeEmitTranscriptFloor = () => {
+      if (floorEmitted) return;
+      if (transcriptChunksPublished > 0) return;
+      if (!relayTap || typeof relayTap.relayTranscriptChunk !== 'function') return;
+      floorEmitted = true;
+      const text = buildFloorText();
+      if (!text) return;
+      const chunk = encodeTranscriptChunk({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } });
+      if (!chunk) {
+        // Canonical bridge couldn't produce a chunk (bridge throw or unmapped
+        // classification) → emit the floor on the text lane rather than dropping
+        // it, exactly like `emitTranscript`, so the cockpit transcript is never
+        // left empty in the very failure mode this floor exists to mitigate.
+        emitHuman(text);
+        return;
+      }
+      // Only skip the text lane when the chunk publish ACTUALLY succeeded. If the
+      // seam throws (a downstream tap implementation bug, not just the built-in
+      // best-effort guard), the floor never reached the relay lane — so fall back
+      // to the text lane, exactly like `emitTranscript`, or the cockpit transcript
+      // could still be empty in that failure mode.
+      let published = false;
+      try { relayTap.relayTranscriptChunk(chunk); published = true; } catch { /* relay best-effort */ }
+      if (published) {
+        transcriptChunksPublished++;
+        // Mirror locally (spy tee + captured stdout) so a --stream watcher and the
+        // result envelope also reflect the floor, matching the mapped-update path.
+        captureHuman(text);
+        return;
+      }
+      // Chunk publish threw → emit the floor on the text lane (relay text + spy
+      // tee + capture) so nothing is dropped.
+      emitHuman(text);
+    };
+
     const handleMessage = (msg) => {
       if (!msg || typeof msg !== 'object') return;
       // A response to one of OUR requests.
@@ -6045,6 +6133,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 +6419,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 +11758,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.5",
+  "version": "1.44.7",
   "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.5",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.44.5",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.44.5",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.44.5",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.44.5",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.44.5",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.44.5"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.44.7",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.44.7",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.44.7",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.44.7",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.44.7",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.44.7",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.44.7"
   }
 }