c8ctl-plugin-nano 1.33.1 → 1.34.0

package/README.md

@@ -274,24 +274,39 @@ its agents' terminals to an operator's cockpit. This rides the app's agentic
 channel (ADR 0056), served **same-port** on the app's own HTTP base URL at path
 **`/agentic`** — not a sidecar, so there's no extra port to open.
 
-**Connecting.** Enrolment is opt-in: a worker only connects when it has both an
-ADR 0028 **identity token** and a **capability credential** (the same `?token=…`
-pattern the blackboard uses). Point it at the app and hand it the two secrets via
-env (or persisted config); the channel URL defaults to the configured nano URL:
+**Connecting — on by default (local-first).** Nano is designed for local use, so
+visibility is **on by default**. Run a worker against a local app and it appears
+live with **zero configuration** — it joins the channel with a well-known
+localhost token in **LOCAL mode** (no credential). The worker presents this
+token to whatever `NANO_AGENTIC_URL` you point it at; the same-machine
+restriction is enforced by the **hub**, which only honours the well-known LOCAL
+token for local/loopback connections:
 
 ```bash
-# Enrol this worker on the app's same-port /agentic channel
+# LOCAL mode (default): appears live with no secrets
 export NANO_AGENTIC_URL=http://localhost:8080     # app base URL; channel is served at /agentic
+c8ctl nano work reviewer
+#   agentic channel (local): announcing presence as ‹worker› on ws://localhost:8080/agentic
+```
+
+**Secure mode (opt-in).** For a shared/remote deployment, enrol the worker with an
+ADR 0028 **identity token** and a **capability credential** (the same `?token=…`
+pattern the blackboard uses). Setting either switches the worker into SECURE mode,
+which requires **both** (fail closed if only one is set):
+
+```bash
+# SECURE mode: real enrolment
+export NANO_AGENTIC_URL=http://localhost:8080
 export NANO_AGENTIC_TOKEN=<identity-token>         # ADR 0028 identity
 export NANO_AGENTIC_CREDENTIAL=<capability-cred>   # capability credential
 c8ctl nano work reviewer
-#   agentic channel: announcing presence as ‹worker› on ws://localhost:8080/agentic
+#   agentic channel (secure): announcing presence as ‹worker› on ws://localhost:8080/agentic
 ```
 
-Without both secrets the worker runs **exactly as before, off the channel** — no
-visibility, no relay, nothing else changes. A valid identity + capability
-connects; an invalid identity is rejected (unauthorized) and a missing capability
-is rejected (forbidden).
+To opt out entirely, set `NANO_AGENTIC=off` (or persisted `agentic: false`) — the
+worker then runs with **no visibility, no relay, nothing else changed**. In secure
+mode a valid identity + capability connects; an invalid identity is rejected
+(unauthorized) and a missing capability is rejected (forbidden).
 
 **How presence appears.** On connect the worker **announces** its identity, its
 `host`, and the set of `jobKeys` it is currently running, then **heartbeats** to

package/c8ctl-plugin.js

@@ -135,6 +135,16 @@ const SUPERVISOR_STATE_FILE = 'supervisor.json';
 const PROCESSOS_DEFAULT_PORT = 8090;
 const DEFAULT_NANO_URL = 'http://localhost:8080';
 
+// The well-known identity token used for LOCAL agentic visibility (security opt-in). Nano is
+// local-first: on the operator's own machine a `nano work` worker joins the visibility channel with
+// zero configuration, so it presents this constant, well-known localhost token — NOT a secret. The
+// worker does not enforce any loopback restriction itself (it presents this token to whatever
+// NANO_AGENTIC_URL is configured); same-machine gating is enforced by the hub, which only honours
+// this well-known token for local/loopback connections. Kept in lock-step with the hub constant in
+// nanobpm/nano-workforce (`app/agentic/channel.ts` LOCAL_AGENTIC_TOKEN). In secure mode (a real
+// NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL) this is never used.
+const LOCAL_AGENTIC_TOKEN = 'nano-local';
+
 // Passive update notifier (npm-style): refresh the latest published version
 // from the registry in a detached background process at most once per day, and
 // surface a one-line "update available" notice at most once per day. Never
@@ -161,6 +171,17 @@ function getLogger() {
     warn: console.warn,
     error: console.error,
     debug: () => {},
+    // Primary command output, written to stdout as-is (mirrors the c8ctl host
+    // logger's `output()`). Used for preformatted, non-structured content such
+    // as the supervisor status table, whose newlines must survive verbatim.
+    // Uses `process.stdout.write` (not `console.log`) so the content is emitted
+    // literally — `console.log` applies `util.format` (mangling stray `%`
+    // sequences) and would append its own newline; here we add exactly one
+    // trailing newline when the text lacks one.
+    output: (msg) => {
+      const s = typeof msg === 'string' ? msg : String(msg);
+      process.stdout.write(s.endsWith('\n') ? s : s + '\n');
+    },
   };
 }
 
@@ -1244,7 +1265,7 @@ function logsCluster(req) {
   const proc = spawn('tail', tailArgs, { stdio: ['ignore', 'inherit', 'inherit'] });
   proc.on('error', (err) => {
     logger.error(`Failed to read logs: ${err.message}`);
-    logger.info(`Log files:\n  ${files.join('\n  ')}`);
+    logger.output(`Log files:\n  ${files.join('\n  ')}`);
   });
 }
 
@@ -3789,30 +3810,54 @@ function buildResultEnvelope(result, { sandbox, image, git, result: agentResult,
  * HTTP base URL at `/agentic`; the identity token + capability credential follow
  * the blackboard's `?token=…` pattern.
  *
+ * Local-first (security opt-in). Nano is designed for local use, so visibility is
+ * ON BY DEFAULT:
+ *   - LOCAL mode (default): no credentials configured — the worker connects with
+ *     the well-known localhost token ({@link LOCAL_AGENTIC_TOKEN}) and no
+ *     capability credential, so it appears live with zero configuration (the hub's
+ *     matching LOCAL mode accepts it).
+ *   - SECURE mode: set NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL (or the
+ *     persisted `agenticToken`/`agenticCredential`) — an ADR 0028 identity token
+ *     AND a capability credential are then sent (enrolment). If only one is set the
+ *     config is incomplete and we stay off (fail closed), returning `null`.
+ *   - OFF: NANO_AGENTIC=off (or 0/false/no), or persisted `agentic:false`.
+ *
  * Env wins over persisted config; the base URL falls back to the configured nano
- * URL (the app's own port). A worker only connects when BOTH an identity token
- * and a capability credential are present (enrolment) — absent either, it runs
- * exactly as before, off the visibility page. Returns `null` when not enrolled.
+ * URL (the app's own port). Returns `null` only when disabled or half-configured.
  *
- * @returns {{ url: string, token: string, credential: string, bufferCapacity: number } | null}
+ * @returns {{ url: string, token: string, credential: string, bufferCapacity: number, secure: boolean } | null}
  */
 function resolveAgenticConfig() {
   const cfg = readConfig();
+  // Explicit off-switch (env wins). Lets an operator fully opt out of visibility.
+  const offSetting = process.env.NANO_AGENTIC
+    ?? (cfg.agentic === false ? 'off' : cfg.agentic);
+  if (/^(0|off|false|no)$/i.test(String(offSetting ?? ''))) return null;
+
   const url = process.env.NANO_AGENTIC_URL
     || cfg.agenticUrl
     || cfg.nanoUrl
     || process.env.NANO_BASE_URL
     || DEFAULT_NANO_URL;
+  if (!url) return null;
   const token = process.env.NANO_AGENTIC_TOKEN || cfg.agenticToken || '';
   const credential = process.env.NANO_AGENTIC_CREDENTIAL || cfg.agenticCredential || '';
-  if (!url || !token || !credential) return null;
   // Outbound hub-down buffer bound (frames). Operator-tunable (C4, #43) so a
   // long expected outage can be given more headroom; resolveBufferCapacity
   // validates it to a positive integer and falls back to the client default.
   const bufferCapacity = resolveBufferCapacity(
     process.env.NANO_AGENTIC_BUFFER_CAPACITY ?? cfg.agenticBufferCapacity,
   );
-  return { url, token, credential, bufferCapacity };
+
+  // SECURE mode: any explicit credential configured means the operator opted into
+  // enrolment — require BOTH halves, fail closed if only one is present.
+  if (token || credential) {
+    if (!token || !credential) return null;
+    return { url, token, credential, bufferCapacity, secure: true };
+  }
+
+  // LOCAL mode (default): well-known localhost token, no capability credential.
+  return { url, token: LOCAL_AGENTIC_TOKEN, credential: '', bufferCapacity, secure: false };
 }
 
 /**
@@ -4135,8 +4180,10 @@ async function workAgent(req, flags) {
   // accessors on `workChannel` (relay-lane sink + connect/disconnect/reconnect
   // lifecycle events) rather than opening their own connection.
   //
-  // Enrolment is opt-in: without an identity token + capability credential the
-  // worker runs exactly as before, off the channel (see resolveAgenticConfig).
+  // Local-first (security opt-in): visibility is ON BY DEFAULT. In LOCAL mode the
+  // worker joins with the well-known localhost token and no credential; SECURE
+  // mode (NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL) sends a real ADR 0028
+  // identity + capability; NANO_AGENTIC=off disables it (see resolveAgenticConfig).
   const agenticCfg = resolveAgenticConfig();
   if (agenticCfg) {
     try {
@@ -4156,7 +4203,8 @@ async function workAgent(req, flags) {
         logger,
       });
       const shown = redactAgenticUrl(buildAgenticUrl(agenticCfg.url, {}));
-      logger.info(`  agentic channel: announcing presence as ${workerName} on ${shown}`);
+      const mode = agenticCfg.secure ? 'secure' : 'local';
+      logger.info(`  agentic channel (${mode}): announcing presence as ${workerName} on ${shown}`);
     } catch (err) {
       // Never let a channel failure stop the worker from doing its actual job.
       workChannel = null;
@@ -4180,7 +4228,7 @@ async function workAgent(req, flags) {
       }
     }
   } else {
-    logger.info('  agentic channel: not enrolled (set NANO_AGENTIC_URL + NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL to appear on the visibility page).');
+    logger.info('  agentic channel: disabled — either the off-switch is set (NANO_AGENTIC=off or persisted agentic:false), or SECURE mode is half-configured (set BOTH NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL). Clear the off-switch to use default LOCAL visibility.');
   }
 
   // C3 (#42): the role's live-terminal mode — a full PTY (streamed on the relay
@@ -5094,6 +5142,27 @@ function formatSupervisorStatus(status) {
   return lines.join('\n');
 }
 
+/**
+ * Print a preformatted supervisor status table as primary command output.
+ *
+ * Preformatted, multi-line text MUST go through the logger's `output()`
+ * channel, never `info()`. In `--output json` mode the c8ctl host logger wraps
+ * an `info()` message in a JSON envelope (`{"status":"info","message":"…"}`),
+ * which escapes every newline to a literal `\n` and collapses the aligned table
+ * onto a single line — the exact breakage this guards against. `output()` writes
+ * the content to stdout verbatim in every output mode (like `raw` command
+ * output), so the table renders correctly regardless of mode. Falls back to
+ * `info()` for a logger without `output()`, and to `console.log` if `logger`
+ * is null/undefined or lacks `info()` (defensive; both the c8ctl host logger
+ * and this plugin's fallback logger provide `output()`).
+ */
+function printSupervisorStatus(logger, status) {
+  const text = formatSupervisorStatus(status);
+  if (logger && typeof logger.output === 'function') logger.output(text);
+  else if (logger && typeof logger.info === 'function') logger.info(text);
+  else console.log(text);
+}
+
 function readSupervisorState() {
   const file = getSupervisorStateFile();
   if (!existsSync(file)) return null;
@@ -5727,7 +5796,7 @@ async function supervisorStatusCmd() {
       const res = await supervisorRequest({ op: 'status' }, { socketPath: getSupervisorSocketPath(), timeoutMs: 500, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
       if (res && res.ok) {
         try { writeSupervisorState(stateFromStatus(res, getSupervisorSocketPath())); } catch { /* best effort */ }
-        logger.info(formatSupervisorStatus(res));
+        printSupervisorStatus(logger, res);
         return;
       }
     } catch { /* no live daemon on the socket — genuinely down */ }
@@ -5743,13 +5812,13 @@ async function supervisorStatusCmd() {
   }
   try {
     const res = await supervisorRequest({ op: 'status' });
-    if (res.ok) { logger.info(formatSupervisorStatus(res)); return; }
+    if (res.ok) { printSupervisorStatus(logger, res); return; }
   } catch { /* fall back to state file below */ }
   // Socket unreachable but pid alive — render from the last persisted state.
-  logger.info(formatSupervisorStatus({
+  printSupervisorStatus(logger, {
     daemon: { pid: running.pid, startedAt: running.startedAt, socket: running.socket },
     workers: (running.workers || []).map((w) => summarizeSupervisorWorker(w)),
-  }));
+  });
 }
 
 async function supervisorAddCmd(req, flags) {
@@ -5862,7 +5931,7 @@ function supervisorLogsCmd(req) {
     if (follow) logger.warn('`--follow` is not supported without `tail` on this platform; printing the current tail only.');
     try {
       const lines = readFileSync(file, 'utf-8').split('\n');
-      logger.info(lines.slice(-200).join('\n'));
+      logger.output(lines.slice(-200).join('\n'));
     } catch (err) { logger.error(`Could not read ${file}: ${err.message}`); }
   });
 }
@@ -7534,6 +7603,7 @@ function parseProcessosRequest(args, flags) {
 export { resolveBinary, findBinary, launcherEnvMarkers };
 export { setConfig, unsetConfig, readConfig, writeConfig, getConfigFile, SETTING_ALIASES };
 export { buildNpmInvocation };
+export { resolveAgenticConfig, LOCAL_AGENTIC_TOKEN };
 export { compareSemver, githubRepoSlug, filterReleasesSince, renderReleaseBody };
 export {
   webConsoleUrl,
@@ -7624,6 +7694,7 @@ export {
   formatDuration,
   summarizeSupervisorWorker,
   formatSupervisorStatus,
+  printSupervisorStatus,
   supervisorStatusSignature,
   supervisorJobCell,
   supervisorWorkerActivityFile,

package/package.json

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