c8ctl-plugin-nano 1.36.1 → 1.37.0

package/README.md

@@ -292,23 +292,28 @@ c8ctl nano work reviewer
 
 **Zero-config hub auto-discovery.** You usually don't even set `NANO_AGENTIC_URL`.
 When nwf runs **embedded**, the engine (`:8080`) serves the console but the
-`/agentic` channel is served by the **embedded app on its own loopback port**
-(e.g. `:3000`); the engine's console proxy deliberately refuses WebSocket
-upgrades (nanobpmn ADR 0057 §3 → `501`), so the channel is unreachable via the
-engine URL. With **no** agentic target configured, `work` therefore
-**auto-discovers** it: it reads `GET <engine>/console/api/projects` and, for each
-running app that advertises an agentic UI port (`appUi.enabled === true` and
-`appUi.port`), probes that app's direct `ws://127.0.0.1:<port>/agentic`. Discovery
-is **loopback-only** and **time-bounded** (≤2s) and never meaningfully delays job
-polling.
+`/agentic` channel is served by the **embedded app on its own port** (e.g.
+`:3000`); the engine's console proxy deliberately refuses WebSocket upgrades
+(nanobpmn ADR 0057 §3 → `501`), so the channel is unreachable via the engine URL.
+With **no** agentic target configured, `work` therefore **auto-discovers** it: it
+reads `GET <engine>/console/api/projects` and, for each running app that
+advertises an agentic UI port (`appUi.enabled === true` and `appUi.port`), probes
+that app's direct `ws://<engine-host>:<port>/agentic`. Discovery runs **against
+the engine's own host** — a local engine keeps probing `127.0.0.1`, while a
+remote/LAN engine (e.g. `merlin.local:8080`) steers the probe back at *itself*
+(`merlin.local:<port>`), never at the worker's own loopback services. It is
+**time-bounded** (≤2s) and never meaningfully delays job polling. The discovered
+host and port are printed for debugging. (An IPv6 literal engine host is bracketed
+in the URL authority, e.g. `ws://[2001:db8::1]:3000/agentic`.)
 
 - **Exactly one app →** the worker connects directly to
-  `ws://127.0.0.1:<appUi.port>/agentic` (bypassing the WS-incapable console proxy)
-  and appears live with **zero configuration**.
+  `ws://<engine-host>:<appUi.port>/agentic` (bypassing the WS-incapable console
+  proxy) and appears live with **zero configuration** — including cross-machine on
+  a trusted LAN.
 - **Two or more apps →** the worker **does not guess**: it prints an `ambiguous`
   error naming each discovered `project → :port` and **stops**. Pin the one you
-  want and re-run: `export NANO_AGENTIC_URL=http://127.0.0.1:<port>` (or persist
-  `agenticUrl`).
+  want and re-run: `export NANO_AGENTIC_URL=http://<engine-host>:<port>` (or
+  persist `agenticUrl`).
 - **Nothing discoverable (e.g. pointed at Camunda, or an API-only gateway) →** the
   worker prints a one-line advisory naming `NANO_AGENTIC_URL` and **continues
   doing real work** with the channel simply absent — discovery never fails the
@@ -319,6 +324,27 @@ used **verbatim** — so an explicit target always wins, and it's also how you
 disambiguate when several apps are running. `NANO_AGENTIC=off` disables the
 channel entirely and attempts **no** discovery.
 
+**Seeing it work — `supervisor status`.** Supervised workers report both the
+engine they poll and their agentic-channel state to `c8ctl nano supervisor
+status` (and the interactive console), so you don't have to read raw worker logs
+to tell whether presence actually reached the Workforce hub. The table gains an
+`ENGINE` column (the engine's `host:port`) and an `AGENTIC` column whose value is
+one of:
+
+| AGENTIC | meaning |
+| --- | --- |
+| `starting` | transient: the worker just spawned and hasn't resolved its channel target yet (pre-`connecting`) |
+| `connected` | presence is live on the hub — you should see this worker in the Cockpit |
+| `connecting` | resolved a hub, socket not open yet (or the hub is unreachable) |
+| `disconnected` | an established channel dropped (hub restart/outage) — it auto-reconnects; also set if the channel failed to start (bad URL/refused socket), in which case it stays disconnected until the worker restarts |
+| `advisory` | nothing discoverable at the engine — **not** in the Cockpit; set `NANO_AGENTIC_URL` |
+| `off` | visibility disabled (`NANO_AGENTIC=off`) |
+| `?` | a live worker not yet reporting, or an older build predating these fields |
+
+If workers show `advisory` (or stay `connecting`) while jobs still run, that's the
+"connected to the engine but empty Cockpit" case: point them at the app with
+`export NANO_AGENTIC_URL=http://<engine-host>:<appUi.port>` (e.g. `:3000`).
+
 **Secure mode (opt-in).** For a deployment where you want the visibility channel
 authenticated (rather than open on the LAN), start the server **and** every worker
 box with the **same** `NANO_AGENTIC_SECRET` — same env-var name, same value on both

package/c8ctl-plugin.js

@@ -4170,6 +4170,21 @@ function isLoopbackHost(hostname) {
   return /^127(?:\.\d{1,3}){3}$/.test(h);
 }
 
+/**
+ * Format a hostname for the authority component of a `ws://`/`http://` URL:
+ * a bare IPv6 literal (contains `:`, not already bracketed) is wrapped in `[…]`,
+ * everything else is used verbatim. Idempotent — an already-bracketed host is
+ * left as-is. Guards against building an invalid `ws://::1:3000/…` when a raw or
+ * normalized IPv6 host (e.g. the `::1` constant) has not been bracketed.
+ *
+ * @param {string} host a hostname from `URL.hostname` or a normalized loopback
+ * @returns {string}
+ */
+function wsHostPart(host) {
+  const h = String(host || '');
+  return h.includes(':') && !h.startsWith('[') ? `[${h}]` : h;
+}
+
 /**
  * Normalise the engine's `GET /console/api/projects` payload into the running
  * embedded apps that advertise an agentic UI port. Accepts the shapes the
@@ -4207,24 +4222,26 @@ function normalizeProjectApps(projects) {
 }
 
 /**
- * Probe whether an embedded app's own loopback `/agentic` endpoint answers a
- * WebSocket upgrade. Connects to `ws://127.0.0.1:<port>/agentic?token=…` and
+ * Probe whether an embedded app's `/agentic` endpoint answers a WebSocket
+ * upgrade. Connects to `ws://<host>:<port>/agentic?token=…` (host defaults to
+ * `127.0.0.1`; a bare IPv6 literal is bracketed for the URL authority) and
  * resolves `true` only if the socket opens within `timeoutMs`; a refused
  * connection, the console proxy's deliberate `501`, a `404`, or a timeout all
- * resolve `false`. Loopback-only and self-cleaning — the probe socket is closed
- * as soon as the outcome is known. Never throws.
+ * resolve `false`. Self-cleaning — the probe socket is closed as soon as the
+ * outcome is known. Never throws.
  *
- * @param {number} port the app's direct loopback port (`appUi.port`)
- * @param {{ token?: string, WebSocketImpl?: Function, timeoutMs?: number }} [opts]
+ * @param {number} port the app's direct agentic port (`appUi.port`)
+ * @param {{ host?: string, token?: string, WebSocketImpl?: Function, timeoutMs?: number }} [opts]
  * @returns {Promise<boolean>}
  */
 function probeAgenticChannel(port, {
+  host = '127.0.0.1',
   token = LOCAL_AGENTIC_TOKEN,
   WebSocketImpl = globalThis.WebSocket,
   timeoutMs = AGENTIC_DISCOVERY_TIMEOUT_MS,
 } = {}) {
   if (typeof WebSocketImpl !== 'function') return Promise.resolve(false);
-  const url = `ws://127.0.0.1:${port}/agentic?token=${encodeURIComponent(token)}`;
+  const url = `ws://${wsHostPart(host)}:${port}/agentic?token=${encodeURIComponent(token)}`;
   return new Promise((resolve) => {
     let done = false;
     let ws;
@@ -4249,19 +4266,21 @@ function probeAgenticChannel(port, {
 
 /**
  * Auto-discover the embedded nwf agentic hub(s) reachable from an engine base
- * URL (#75). Reads `GET <engine>/console/api/projects`, keeps the apps that
- * advertise an agentic UI port, and WS-probes each app's direct loopback
- * `/agentic` to confirm the channel is actually served there (bypassing the
- * WS-incapable console proxy). Loopback-only (the engine host itself must be
- * loopback, since the response steers a local port probe), enforces a single
- * shared time budget across the fetch + probes, and is fail-open: any error —
- * not a nano engine (Camunda), a non-loopback engine, network failure,
- * malformed body, or an overall timeout — degrades to `[]` so the worker's real
- * job is never blocked.
+ * URL (#75, #96). Reads `GET <engine>/console/api/projects`, keeps the apps that
+ * advertise an agentic UI port, and WS-probes each app's `/agentic` **on the
+ * engine's own host** to confirm the channel is actually served there (bypassing
+ * the WS-incapable console proxy). Works cross-machine on a trusted LAN: a
+ * loopback engine probes `127.0.0.1`, a remote engine (e.g. `merlin.local`)
+ * probes that same host — the port is taken from the projects API but the host is
+ * always the engine's, so a rogue projects API can never steer a probe at the
+ * worker's own loopback (#76). Enforces a single shared time budget across the
+ * fetch + probes, and is fail-open: any error — not a nano engine (Camunda),
+ * network failure, malformed body, or an overall timeout — degrades to `[]` so
+ * the worker's real job is never blocked.
  *
- * @param {string} engineBaseUrl the engine base URL (e.g. `http://localhost:8080`)
+ * @param {string} engineBaseUrl the engine base URL (e.g. `http://merlin.local:8080`)
  * @param {{ token?: string, fetchImpl?: Function, wsProbe?: Function, timeoutMs?: number }} [opts]
- * @returns {Promise<Array<{ project: string, port: number, label?: string }>>}
+ * @returns {Promise<Array<{ project: string, port: number, label?: string, host: string }>>}
  */
 async function discoverAgenticHubs(engineBaseUrl, {
   token = LOCAL_AGENTIC_TOKEN,
@@ -4273,16 +4292,21 @@ async function discoverAgenticHubs(engineBaseUrl, {
     return [];
   }
   const base = engineBaseUrl.replace(/\/+$/, '');
-  // Loopback-only: discovery probes 127.0.0.1:<port> using a port advertised by
-  // the engine's projects API, so a non-loopback (remote) engine could steer a
-  // local port probe. Refuse discovery unless the engine host is loopback (#76).
+  // Discover against the ENGINE's own host — the app is embedded in the engine,
+  // so its /agentic port lives on the same host the worker already trusts as its
+  // engine (that's where it pulls jobs from). A loopback engine keeps probing
+  // 127.0.0.1 (unchanged local behaviour); a remote/LAN engine (e.g.
+  // merlin.local) steers the probe back to ITSELF, never at the worker's own
+  // loopback services — which was the actual #76 concern (a rogue projects API
+  // making the worker probe its own localhost). So the port comes from the
+  // engine's projects API, but the HOST is always the engine's, never guessed.
   let host;
   try {
     host = new URL(base).hostname;
   } catch {
     return [];
   }
-  if (!isLoopbackHost(host)) return [];
+  const probeHost = isLoopbackHost(host) ? '127.0.0.1' : host;
   // Single discovery budget: the projects fetch and the WS probes share ONE
   // deadline, so total discovery can't approach 2× timeoutMs (the fetch could
   // consume ~timeoutMs and then each probe was previously given a fresh full
@@ -4304,10 +4328,13 @@ async function discoverAgenticHubs(engineBaseUrl, {
   if (apps.length === 0) return [];
   const remainingMs = deadline - Date.now();
   if (remainingMs <= 0) return [];
-  // Probe candidate ports concurrently within the remaining shared budget.
+  // Probe candidate ports concurrently within the remaining shared budget. Each
+  // surviving hub carries the engine host so the caller builds the right URL.
   const settled = await Promise.all(apps.map(async (app) => {
     try {
-      return (await wsProbe(app.port, { token, timeoutMs: remainingMs })) ? app : null;
+      return (await wsProbe(app.port, { host: probeHost, token, timeoutMs: remainingMs }))
+        ? { ...app, host: probeHost }
+        : null;
     } catch {
       return null;
     }
@@ -4324,7 +4351,8 @@ async function discoverAgenticHubs(engineBaseUrl, {
  *     half-configured. No discovery attempted.
  *   - `{ status: 'connect', config }` — a target to connect to. Either the
  *     explicit `NANO_AGENTIC_URL`/`agenticUrl` verbatim (no discovery), or the
- *     single discovered app's direct `ws://127.0.0.1:<port>/agentic` loopback.
+ *     single discovered app's `ws://<engineHost>:<port>/agentic` (loopback for a
+ *     local engine, the engine's LAN host for a remote one).
  *   - `{ status: 'ambiguous', message, candidates }` — two+ apps expose a
  *     channel. Hard stop for the worker: it must not silently pick one.
  *   - `{ status: 'advisory', message }` — nothing discoverable (zero matches,
@@ -4342,11 +4370,24 @@ async function resolveAgenticTarget(opts = {}) {
 
   const hubs = await discoverAgenticHubs(base.url, { token: base.token, ...opts });
 
+  // The host to suggest in operator-facing messages: the engine's own host
+  // (bracketed if an IPv6 literal, so the suggested URL authority is valid), so a
+  // remote-engine advisory names the reachable LAN host rather than 127.0.0.1.
+  let suggestHost = '127.0.0.1';
+  try {
+    const h = new URL(base.url).hostname;
+    suggestHost = wsHostPart(isLoopbackHost(h) ? '127.0.0.1' : h);
+  } catch { /* keep the loopback default */ }
+
   if (hubs.length === 1) {
-    const { project, port } = hubs[0];
+    const { project, port, host } = hubs[0];
     return {
       status: 'connect',
-      config: { ...base, url: `http://127.0.0.1:${port}`, discovered: { project, port } },
+      config: {
+        ...base,
+        url: `http://${wsHostPart(host)}:${port}`,
+        discovered: { project, port, host },
+      },
     };
   }
   if (hubs.length > 1) {
@@ -4355,14 +4396,101 @@ async function resolveAgenticTarget(opts = {}) {
       status: 'ambiguous',
       candidates: hubs,
       message: `multiple embedded apps expose an agentic channel (${list}); refusing to guess. `
-        + 'Disambiguate by setting NANO_AGENTIC_URL=http://127.0.0.1:<port> (or persisted agenticUrl) to the one you want.',
+        + `Disambiguate by setting NANO_AGENTIC_URL=http://${suggestHost}:<port> (or persisted agenticUrl) to the one you want.`,
     };
   }
   return {
     status: 'advisory',
     message: `agentic visibility was not discoverable at ${base.url} — the embedded app port could `
       + 'not be found (not a nano engine, or its console projects API is absent). Set '
-      + 'NANO_AGENTIC_URL=http://127.0.0.1:<appUi.port> to enable the visibility channel. Continuing without it.',
+      + `NANO_AGENTIC_URL=http://${suggestHost}:<appUi.port> to enable the visibility channel. Continuing without it.`,
+  };
+}
+
+/**
+ * Collapse an agentic disconnect/failure detail into the single short string the
+ * marker's `agentic.message` field carries (#99 contract). Accepts the close
+ * `info` the work channel's onDisconnect passes (transport-dependent shape, e.g.
+ * `{ code, reason, local }`), a thrown Error, or a bare string.
+ * @param {unknown} x diagnostic input (close info, Error, or string)
+ * @returns {string|null} a human-readable reason, or null when nothing useful
+ */
+function normalizeAgenticMessage(x) {
+  // Collapse an agentic disconnect/failure detail into the single short string
+  // the marker's `agentic.message` field carries (#99 contract). Accepts the
+  // close `info` the work channel's onDisconnect passes (transport-dependent
+  // shape, e.g. `{ code, reason, local }`), a thrown Error, or a bare string,
+  // and returns a human-readable reason or null when there is nothing useful.
+  if (x == null) return null;
+  if (typeof x === 'string') return x.trim() || null;
+  if (x instanceof Error) return x.message ? String(x.message) : String(x);
+  if (typeof x === 'object') {
+    const reason = typeof x.reason === 'string' ? x.reason.trim() : '';
+    const code = x.code != null && x.code !== '' ? String(x.code) : '';
+    if (reason && code) return `${reason} (code ${code})`;
+    if (reason) return reason;
+    if (code) return `close code ${code}`;
+    if (x.message) return String(x.message);
+    if (x.local === true) return 'closed locally';
+    if (x.local === false) return 'connection dropped';
+    return null;
+  }
+  return String(x);
+}
+
+/**
+ * Map a resolved `resolveAgenticTarget` result to the INITIAL agentic-channel
+ * state persisted on the supervisor activity marker (#99). Pure so the marker
+ * producer's state transitions are unit-testable without a live broker/SDK
+ * client — a regression here would leave every supervised worker stuck at
+ * `?`/`starting`, which the reader/renderer tests can't catch. `connected`/
+ * `disconnected` are layered on top of this base by the channel lifecycle
+ * (a `{ ...state, status }` merge). The `ambiguous` status is a hard-stop
+ * handled by the caller (never reaches the marker), so it degrades to `off`
+ * here. `safeUrl` mirrors the caller's defensive display-URL builder.
+ * @param {{ status?: string, config?: any, message?: string }} target
+ * @param {(u: string) => (string|null)} [safeUrl]
+ */
+function agenticStateForTarget(target, safeUrl = (u) => u) {
+  switch (target?.status) {
+    case 'connect': {
+      const cfg = target.config || {};
+      return {
+        status: 'connecting',
+        mode: cfg.secure ? 'secure' : 'local',
+        url: safeUrl(cfg.url),
+        discovered: cfg.discovered || null,
+      };
+    }
+    case 'advisory':
+      // Retain the discovery diagnostic so the supervisor can distinguish a
+      // missing projects API, a timeout, or a non-Nano endpoint (#99).
+      return { status: 'advisory', message: target.message || null };
+    case 'off':
+    default:
+      return { status: 'off' };
+  }
+}
+
+/**
+ * Build the supervisor activity-marker payload the worker atomically writes for
+ * `supervisor status`. Pure so the producer's field set is unit-testable without
+ * spawning a worker: the reader/renderer tests exercise a hand-written marker and
+ * `agenticStateForTarget` in isolation, so a regression that dropped `engine` or
+ * `agentic` from THIS payload — leaving every supervised worker's Engine/Agentic
+ * column stuck at `?` — would otherwise slip through. `jobs` is the live active-job
+ * list; `busy` is derived so callers can't desync it from `jobs`.
+ * @param {{ pid:number, updatedAt:number, jobs:Array<{key:string,type:string,since:number}>, engine:(string|null), agentic:object }} fields
+ */
+function buildActivityPayload({ pid, updatedAt, jobs, engine, agentic }) {
+  const jobList = Array.isArray(jobs) ? jobs : [];
+  return {
+    pid,
+    updatedAt,
+    busy: jobList.length > 0,
+    jobs: jobList,
+    engine: engine ?? null,
+    agentic,
   };
 }
 
@@ -4654,10 +4782,29 @@ async function workAgent(req, flags) {
     installParentDeathWatchdog({ parentPid: Number.isInteger(daemonPid) ? daemonPid : undefined });
   }
   const activeJobs = new Map(); // jobKey -> { type, since (ms epoch) }
+  // Which engine this worker polls jobs from + the live agentic-visibility
+  // channel status, both surfaced to `supervisor status` via the activity
+  // marker (#99). `agenticState` starts 'starting' and is updated once the
+  // channel target is resolved and again on each connect/disconnect below.
+  // The engine must name the ACTUAL polling authority: jobs are activated by
+  // `camunda.createJobWorker()` against the active c8ctl profile engine
+  // (`camunda.getConfig().restAddress`), whereas `restConfig` can honor the
+  // auxiliary NANO_REST_URL/NANO_BASE_URL/nanoUrl overrides (for `--auto`
+  // reads). Derive from the profile engine, using restConfig only as a
+  // fallback, so the column can't advertise an override host jobs aren't
+  // polled from.
+  const workerEngine = (() => {
+    try {
+      const profileBase = normalizeRestBase(camunda?.getConfig?.()?.restAddress);
+      if (profileBase) return profileBase;
+    } catch { /* degrade to the auxiliary REST config below */ }
+    return restConfig?.baseUrl || null;
+  })();
+  let agenticState = { status: 'starting' };
   const writeActivity = () => {
     if (!activityFile) return;
     const jobs = [...activeJobs.entries()].map(([key, v]) => ({ key, type: v.type, since: v.since }));
-    const payload = { pid: process.pid, updatedAt: Date.now(), busy: jobs.length > 0, jobs };
+    const payload = buildActivityPayload({ pid: process.pid, updatedAt: Date.now(), jobs, engine: workerEngine, agentic: agenticState });
     const tmp = `${activityFile}.${process.pid}.tmp`;
     try {
       mkdirSync(dirname(activityFile), { recursive: true });
@@ -4706,9 +4853,22 @@ async function workAgent(req, flags) {
   // NANO_AGENTIC=off disables it (see resolveAgenticConfig).
   const agenticTarget = await resolveAgenticTarget({ logger });
   let agenticCfg = null;
+  // buildAgenticUrl can throw on a malformed/unsupported explicit NANO_AGENTIC_URL.
+  // This is only the display URL for the activity marker, so compute it
+  // defensively: a bad URL must be recorded as a channel failure (via the
+  // createWorkChannel try/catch below), never crash the worker before it — which
+  // would violate the best-effort channel contract and cause a restart loop.
+  const safeAgenticDisplayUrl = (u) => {
+    try { return redactAgenticUrl(buildAgenticUrl(u, {})); }
+    catch { return null; }
+  };
   switch (agenticTarget.status) {
     case 'connect':
       agenticCfg = agenticTarget.config;
+      // 'connecting' until the socket actually opens (wired on the channel
+      // lifecycle below). Carry the resolved mode/target/discovery so the
+      // supervisor can show WHERE presence is being announced (#99).
+      agenticState = agenticStateForTarget(agenticTarget, safeAgenticDisplayUrl);
       break;
     case 'ambiguous':
       // The operator ran with visibility on-by-default but the hub is
@@ -4717,13 +4877,19 @@ async function workAgent(req, flags) {
       process.exit(1);
       break;
     case 'advisory':
+      agenticState = agenticStateForTarget(agenticTarget);
       logger.info(`  agentic channel: ${agenticTarget.message}`);
       break;
     case 'off':
     default:
+      agenticState = agenticStateForTarget(agenticTarget);
       logger.info('  agentic channel: disabled — the off-switch is set (NANO_AGENTIC=off or persisted agentic:false). Clear it to use default LOCAL visibility.');
       break;
   }
+  // Persist the resolved channel state to the activity marker now, so
+  // `supervisor status` reflects connecting/advisory/off immediately, before
+  // the socket opens (or without a channel at all).
+  writeActivity();
   if (agenticCfg) {
     try {
       workChannel = await createWorkChannel({
@@ -4744,12 +4910,35 @@ async function workAgent(req, flags) {
       const shown = redactAgenticUrl(buildAgenticUrl(agenticCfg.url, {}));
       const mode = agenticCfg.secure ? 'secure' : 'local';
       if (agenticCfg.discovered) {
-        logger.info(`  agentic channel: auto-discovered ${agenticCfg.discovered.project} on the embedded app port :${agenticCfg.discovered.port} (bypassing the WS-incapable console proxy).`);
+        const d = agenticCfg.discovered;
+        logger.info(`  agentic channel: auto-discovered ${d.project} on the app's /agentic port ${wsHostPart(d.host)}:${d.port} (bypassing the WS-incapable console proxy).`);
       }
       logger.info(`  agentic channel (${mode}): announcing presence as ${workerName} on ${shown}`);
+      // Track the live connection state on the activity marker so the
+      // supervisor shows connected↔disconnected transitions (#99). onConnect
+      // fires only for listeners present at first open, so also reconcile the
+      // already-open case synchronously via connected(). If the socket opened
+      // and then dropped inside the createWorkChannel() await window (before
+      // these listeners existed), connected() is false but everConnected() is
+      // true — record that as `disconnected` rather than leaving it stuck at
+      // `connecting`. A close carries a normalized diagnostic under the contract
+      // `agentic.message` field (not `reason`) so a hub drop explains WHY; a
+      // fresh (re)connect clears any stale message.
+      const markAgentic = (status, message = null) => { agenticState = { ...agenticState, status, message }; writeActivity(); };
+      workChannel.onConnect(() => markAgentic('connected'));
+      workChannel.onReconnect(() => markAgentic('connected'));
+      workChannel.onDisconnect((info) => markAgentic('disconnected', normalizeAgenticMessage(info)));
+      if (workChannel.connected()) markAgentic('connected');
+      else if (workChannel.everConnected()) markAgentic('disconnected');
     } catch (err) {
       // Never let a channel failure stop the worker from doing its actual job.
       workChannel = null;
+      // Retain the failure reason on the marker so the supervisor can show WHY
+      // presence dropped (bad URL, refused socket, …), not just `disconnected`.
+      // The contract diagnostic field is `agentic.message` (#99), matching the
+      // live-disconnect path above — keep the key consistent, not `reason`.
+      agenticState = { ...agenticState, status: 'disconnected', message: normalizeAgenticMessage(err) };
+      writeActivity();
       logger.warn(`  agentic channel unavailable (${err?.message || err}); continuing without visibility.`);
     }
     // C4 (#43): observe the client's built-in outbound buffer across the
@@ -5614,6 +5803,8 @@ function summarizeSupervisorWorker(w, now = Date.now()) {
   // Per-job activity (supervised workers only). Guard on pid so a stale marker
   // left by a previous incarnation can't show a dead job as in-flight.
   let activity = null; // { state: 'busy'|'idle', jobs: [{ key, type, sinceMs, sinceEpochMs }] }
+  let engine = null; // job-polling engine base URL this worker reported (#99)
+  let agentic = null; // { status, mode, url, discovered } agentic-channel state (#99)
   if (alive) {
     const act = readWorkerActivity(w.id);
     if (act && act.pid === w.pid) {
@@ -5628,6 +5819,10 @@ function summarizeSupervisorWorker(w, now = Date.now()) {
           }))
         : [];
       activity = { state: jobs.length > 0 ? 'busy' : 'idle', jobs };
+      // Engine + agentic-channel status ride the same pid-guarded marker, so a
+      // stale incarnation can't show a dead worker as connected to a hub.
+      engine = typeof act.engine === 'string' && act.engine ? act.engine : null;
+      agentic = act.agentic && typeof act.agentic === 'object' ? act.agentic : null;
     }
     // No marker (or a stale-pid one): leave activity null → rendered as unknown.
   }
@@ -5642,6 +5837,8 @@ function summarizeSupervisorWorker(w, now = Date.now()) {
     lastExit: w.lastExit ?? null,
     args: Array.isArray(w.args) ? w.args : [],
     activity,
+    engine,
+    agentic,
   };
 }
 
@@ -5668,6 +5865,10 @@ function supervisorStatusSignature(workers) {
       w.activity
         ? w.activity.jobs.map((j) => `${j.key}\u0000${j.type ?? ''}`).sort()
         : null,
+      // Engine + agentic-channel status: a connect/disconnect or an engine
+      // change is a real transition that must repaint attached consoles (#99).
+      w.engine ?? '',
+      w.agentic ? (w.agentic.status ?? '') : null,
     ]),
   );
 }
@@ -5684,6 +5885,37 @@ function supervisorJobCell(w) {
   return `${first.key}${more}${dur}`;
 }
 
+/**
+ * ENGINE cell: the authority (host:port) of the engine this worker polls jobs
+ * from, so an operator can see cross-machine fleets at a glance. `-` for a
+ * down/stopping worker, `?` for a live worker not (yet) reporting or on an
+ * older build whose marker predates this field. A non-URL engine string falls
+ * back to the raw value.
+ */
+function supervisorEngineCell(w) {
+  if (w.state !== 'running') return '-';
+  if (!w.activity) return '?'; // alive but not reporting
+  if (!w.engine) return '?'; // reporting, but marker predates the engine field
+  try {
+    const host = new URL(w.engine).host;
+    return host || String(w.engine); // a scheme-less string parses host-empty
+  } catch { return String(w.engine); }
+}
+
+/**
+ * AGENTIC cell: the visibility-channel status word
+ * (`connected`/`connecting`/`disconnected`/`advisory`/`off`/`starting`), so an
+ * operator can tell whether presence actually reached the Workforce hub. `-`
+ * for a down/stopping worker, `?` for a live worker not (yet) reporting or on an
+ * older build whose marker predates this field.
+ */
+function supervisorAgenticCell(w) {
+  if (w.state !== 'running') return '-';
+  if (!w.activity) return '?'; // alive but not reporting
+  if (!w.agentic || !w.agentic.status) return '?'; // marker predates the agentic field
+  return String(w.agentic.status);
+}
+
 /**
  * Re-age a supervisor status snapshot to `now`, recomputing the ticking
  * durations (`uptimeMs`, per-job `sinceMs`) from the absolute base epochs the
@@ -5829,14 +6061,19 @@ function formatSupervisorStatus(status) {
     id: String(w.id),
     profile: String(w.profile),
     state: String(w.state),
+    engine: supervisorEngineCell(w),
+    agentic: supervisorAgenticCell(w),
     job: supervisorJobCell(w),
     pid: w.pid ? String(w.pid) : '-',
     restarts: String(w.restarts),
     uptime: w.state === 'running' ? formatDuration(w.uptimeMs) : '-',
     last: w.lastExit ? String(w.lastExit) : '-',
   }));
-  const head = { id: 'ID', profile: 'PROFILE', state: 'STATE', job: 'JOB', pid: 'PID', restarts: 'RESTARTS', uptime: 'UPTIME', last: 'LAST EXIT' };
-  const cols = ['id', 'profile', 'state', 'job', 'pid', 'restarts', 'uptime', 'last'];
+  // ENGINE + AGENTIC sit early (just after STATE) so the pinned live view's
+  // width clamp (which trims from the right) drops the least-critical columns
+  // (LAST EXIT, UPTIME) first and keeps the visibility diagnostics visible.
+  const head = { id: 'ID', profile: 'PROFILE', state: 'STATE', engine: 'ENGINE', agentic: 'AGENTIC', job: 'JOB', pid: 'PID', restarts: 'RESTARTS', uptime: 'UPTIME', last: 'LAST EXIT' };
+  const cols = ['id', 'profile', 'state', 'engine', 'agentic', 'job', 'pid', 'restarts', 'uptime', 'last'];
   const width = {};
   for (const c of cols) width[c] = Math.max(head[c].length, ...rows.map((r) => r[c].length));
   const fmt = (r) => '  ' + cols.map((c) => r[c].padEnd(width[c])).join('  ');
@@ -8681,6 +8918,11 @@ export {
   printSupervisorStatus,
   supervisorStatusSignature,
   supervisorJobCell,
+  supervisorEngineCell,
+  supervisorAgenticCell,
+  agenticStateForTarget,
+  normalizeAgenticMessage,
+  buildActivityPayload,
   supervisorWorkerActivityFile,
   WORK_FORWARD_FLAGS,
   installParentDeathWatchdog,
@@ -8741,7 +8983,7 @@ export const metadata = {
         { command: 'NANO_AGENTIC_URL=http://localhost:8080 NANO_AGENTIC_SECRET=<shared-secret> c8ctl nano work reviewer', description: 'Enrol the worker on the app\'s same-port /agentic channel in SECURE mode (same NANO_AGENTIC_SECRET as the server) so it appears live (presence + relay terminals) on the Workforce visibility page' },
         { command: 'c8ctl nano supervisor start --worker reviewer --worker coder', description: 'Start a detached supervisor managing several workers from one terminal' },
         { command: 'c8ctl nano supervisor', description: 'Attach an interactive console to the supervisor (detach with Ctrl-D, leaving it running)' },
-        { command: 'c8ctl nano supervisor status', description: 'List supervised workers (pid, state, serviced job / idle, restarts, uptime) without the console' },
+        { command: 'c8ctl nano supervisor status', description: 'List supervised workers (state, ENGINE + AGENTIC visibility diagnostics, serviced job / idle, pid, restarts, uptime) without the console' },
         { command: 'c8ctl nano supervisor add decider --max-parallel 2', description: 'Add a supervised worker (forwarding work flags) to the running supervisor' },
         { command: 'c8ctl nano supervisor add reviewer --instances 3', description: 'Add 3 distinct auto-named instances of a profile in one call' },
         { command: 'c8ctl nano supervisor restart reviewer', description: 'Restart a supervised worker by id or profile' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.36.1",
+  "version": "1.37.0",
   "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.36.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.36.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.37.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.37.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.37.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.37.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.37.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.37.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.37.0"
   }
 }

package/work-channel.mjs

@@ -118,6 +118,7 @@ function presenceCapability(capability, jobs) {
  * @property {(fn: (info: object) => void) => () => void} onDisconnect subscribe to channel close
  * @property {(fn: () => void) => () => void} onReconnect subscribe to reconnects (every open after the first)
  * @property {() => boolean} connected whether the channel is currently open
+ * @property {() => boolean} everConnected whether the channel has ever opened (stays true after a later close)
  * @property {() => number} buffered outbound frames currently buffered awaiting the channel
  * @property {(reason?: string) => Promise<void>} stop deregister + close cleanly
  */
@@ -272,6 +273,12 @@ export async function createWorkChannel(opts) {
     onReconnect: subscribe(reconnectListeners),
     onDisconnect: subscribe(disconnectListeners),
     connected: () => client.connected,
+    // Whether the channel has ever opened (even if it has since closed). Lets a
+    // late subscriber tell "still connecting, never opened" (false) apart from
+    // "opened then dropped before I subscribed" (true), so an initial close that
+    // fires inside the createWorkChannel() await window is reconciled to
+    // `disconnected` rather than left stuck at `connecting`.
+    everConnected: () => hasConnected,
     buffered: () => client.buffered,
     async stop(reason = 'worker stopped') {
       try {