c8ctl-plugin-nano 1.26.3 → 1.28.0

package/agentic-loader-hook.mjs

@@ -0,0 +1,42 @@
+// Module-customization RESOLVE hook (Node `module.register`) — the single
+// mechanism that makes `@nanobpm/urban-agent-client` loadable under stock Node.
+//
+// Why this exists (the C0 constraint, jwulf/c8ctl-plugin-nano#39):
+// the published worker client funnels the S0 wire contract through
+// `dist/protocol.js`, which imports `@nanobpm/agentic/source/protocol` — raw
+// TypeScript — on the assumption the consumer runs under a type-stripping
+// loader. This repo runs on stock Node (`node --test`, `nano work`), which
+// REFUSES to type-strip `.ts` under `node_modules`
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so a bare `import` of the
+// client throws before any of C2's channel code can run.
+//
+// The redirect below rewrites every `@nanobpm/agentic/source/*` specifier to
+// the package's COMPILED `@nanobpm/agentic/*` `dist` export. Source and dist are
+// the same S0 contract — both are held to the one shared conformance corpus
+// (`agentic-conformance.test.mjs`) — so this is a pure packaging redirect, not a
+// behavioural change: the client ends up bound to the exact codec/grammar this
+// repo already runs green. When the client is republished to import agentic's
+// `dist` directly, this hook becomes a no-op and can be retired.
+//
+// Registered lazily from `loadAgenticClient()` in `agentic.mjs` (the single
+// client swap point) so it is active before the client's module graph loads.
+
+const SOURCE_PREFIX = '@nanobpm/agentic/source/';
+
+/**
+ * Node ESM resolve hook. Redirects the client's raw-`.ts` source imports to the
+ * compiled dist subpath exports; passes everything else through untouched.
+ *
+ * @param {string} specifier the requested module specifier
+ * @param {import('node:module').ResolveHookContext} context resolution context
+ * @param {(s: string, c?: object) => unknown} next the next hook in the chain
+ */
+export async function resolve(specifier, context, next) {
+  if (specifier === '@nanobpm/agentic/source') {
+    return next('@nanobpm/agentic', context);
+  }
+  if (specifier.startsWith(SOURCE_PREFIX)) {
+    return next(`@nanobpm/agentic/${specifier.slice(SOURCE_PREFIX.length)}`, context);
+  }
+  return next(specifier, context);
+}

package/agentic.mjs

@@ -0,0 +1,133 @@
+// Single import surface for the Nano agentic-visibility plane (ADR 0056 —
+// Magikcraft/nano-bpm#670) inside this plugin.
+//
+// This is slice C0 of the agent-visibility epic (jwulf/c8ctl-plugin-nano#38).
+// The sibling slices — C2 presence (#41), C3 PTY relay (#42) and C4 buffer
+// (#43) — MUST import the wire contract and the worker client through *this*
+// module rather than reaching into `@nanobpm/agentic` subpaths or
+// `@nanobpm/urban-agent-client` directly. One place to import, one place to
+// swap when the upstream packaging changes.
+//
+// Nothing here is re-declared: every frame, lane, family, token, vocab and
+// payload type is CONSUMED from the published `@nanobpm/agentic` package, and
+// the worker-side channel client is CONSUMED from `@nanobpm/urban-agent-client`.
+// The shared conformance corpus (`@nanobpm/agentic/protocol/conformance`) keeps
+// this repo's consumption in lock-step with the hub — see
+// `agentic-conformance.test.mjs`.
+
+// Node's module-customization registrar, used lazily by `loadAgenticClient()`
+// to install the source→dist resolve hook before the worker client loads.
+import { register as moduleRegister } from 'node:module';
+
+// ---------------------------------------------------------------------------
+// Wire contract — @nanobpm/agentic/protocol (S0, the single source of truth).
+// The codec, routing-token grammar, vocab schema and per-family payload
+// validators. These resolve to the package's compiled `dist`, so they load
+// under stock Node.
+// ---------------------------------------------------------------------------
+export {
+  // message families
+  MESSAGE_FAMILIES,
+  FAMILY_CODES,
+  familyForCode,
+  isMessageFamily,
+  // QoS lanes
+  QOS_LANES,
+  LANE_CODES,
+  laneForCode,
+  lanePriority,
+  isQosLane,
+  compareFrameOrder,
+  // frame codec
+  encodeFrame,
+  decodeFrame,
+  FrameDecodeError,
+  FrameEncodeError,
+  FRAME_MAGIC,
+  FRAME_VERSION,
+  FRAME_HEADER_BYTES,
+  MAX_SEQ,
+  // routing tokens
+  parseToken,
+  formatToken,
+  isValidToken,
+  isSegmentName,
+  isSeatLabel,
+  TokenParseError,
+  // vocab schema
+  validateVocabDocument,
+  // per-family payload contracts
+  validatePayload,
+  // language-neutral hex helpers (used to hold the codec to the corpus)
+  bytesToHex,
+  hexToBytes,
+} from '@nanobpm/agentic/protocol';
+
+// ---------------------------------------------------------------------------
+// Visibility families. Each is re-exported wholesale so a consumer picks the
+// namespace it needs (channel transport, presence, relay lane, transcript)
+// without re-declaring any of it. Namespaced re-exports keep the surface tidy
+// and avoid symbol collisions between the families.
+// ---------------------------------------------------------------------------
+export * as channel from '@nanobpm/agentic/channel';
+export * as presence from '@nanobpm/agentic/presence';
+export * as relay from '@nanobpm/agentic/relay';
+export * as transcript from '@nanobpm/agentic/transcript';
+
+// ---------------------------------------------------------------------------
+// Worker-side channel client — @nanobpm/urban-agent-client.
+//
+// The client's published `dist/protocol.js` imports the contract from
+// `@nanobpm/agentic/source/protocol` (raw TypeScript) on the assumption the
+// consumer runs under a type-stripping loader. Stock Node — which this repo's
+// `node --test` uses — refuses to strip types under `node_modules`
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so a *static* re-export of the
+// client would make this whole surface fail to load. To keep C0's surface
+// loadable everywhere while still routing all client consumption through one
+// swap point, the client is exposed behind a lazy async loader.
+//
+// C2 (#41) resolves that constraint HERE, at the single swap point: before the
+// client's module graph loads, `loadAgenticClient()` registers a resolve hook
+// (`agentic-loader-hook.mjs`) that redirects the client's raw-`.ts`
+// `@nanobpm/agentic/source/*` imports to the compiled `@nanobpm/agentic/*`
+// `dist` exports. Source and dist are the same S0 contract (one shared
+// conformance corpus), so the client loads and runs under stock Node with no
+// change in behaviour. When the client is republished to import agentic's dist
+// directly, the redirect self-neutralises.
+//
+// @typedef {import('@nanobpm/urban-agent-client')} AgenticClientModule
+/** @type {Promise<AgenticClientModule> | undefined} */
+let clientModulePromise;
+
+// Guards single registration of the source→dist resolve hook (idempotent).
+let sourceRedirectRegistered = false;
+
+/**
+ * Register the `@nanobpm/agentic/source/*` → `dist` resolve hook exactly once,
+ * so the worker client is importable under stock Node. Safe to call repeatedly;
+ * only the first call registers. Runs before any `import()` of the client so the
+ * hook is active for the client's whole module graph.
+ */
+function ensureClientLoadable() {
+  if (sourceRedirectRegistered) return;
+  sourceRedirectRegistered = true;
+  moduleRegister('./agentic-loader-hook.mjs', import.meta.url);
+}
+
+/**
+ * Load the published worker-side agentic channel client
+ * (`@nanobpm/urban-agent-client`). Memoised so repeated calls share one module
+ * instance. Import the client only through this accessor so there is a single
+ * place to consume it from across the plugin.
+ *
+ * @returns {Promise<AgenticClientModule>} the client module namespace, exposing
+ *   `connectAgenticChannel`, `AgenticClient`, `OutboundRing`, the websocket
+ *   transport and the re-exported protocol symbols.
+ */
+export function loadAgenticClient() {
+  if (clientModulePromise === undefined) {
+    ensureClientLoadable();
+    clientModulePromise = import('@nanobpm/urban-agent-client');
+  }
+  return clientModulePromise;
+}

package/c8ctl-plugin.js

@@ -57,6 +57,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { createInterface as createReadline } from 'node:readline';
 import { platformForHost } from './platforms.mjs';
+import { createWorkChannel, redactAgenticUrl, buildAgenticUrl } from './work-channel.mjs';
 
 const requireFromHere = createRequire(import.meta.url);
 const pluginDir = dirname(fileURLToPath(import.meta.url));
@@ -3236,6 +3237,32 @@ function buildResultEnvelope(result, { sandbox, image, git, result: agentResult
   return env;
 }
 
+/**
+ * Resolve the agentic-visibility channel connection target + credentials for a
+ * worker (ADR 0056 — slice C2). The channel is served same-port on the app's own
+ * HTTP base URL at `/agentic`; the identity token + capability credential follow
+ * the blackboard's `?token=…` pattern.
+ *
+ * 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.
+ *
+ * @returns {{ url: string, token: string, credential: string } | null}
+ */
+function resolveAgenticConfig() {
+  const cfg = readConfig();
+  const url = process.env.NANO_AGENTIC_URL
+    || cfg.agenticUrl
+    || cfg.nanoUrl
+    || process.env.NANO_BASE_URL
+    || DEFAULT_NANO_URL;
+  const token = process.env.NANO_AGENTIC_TOKEN || cfg.agenticToken || '';
+  const credential = process.env.NANO_AGENTIC_CREDENTIAL || cfg.agenticCredential || '';
+  if (!url || !token || !credential) return null;
+  return { url, token, credential };
+}
+
 /**
  * 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.
@@ -3480,19 +3507,66 @@ async function workAgent(req, flags) {
       /* best effort — activity is advisory, never fail a job over it */
     }
   };
+  // The agentic-visibility channel, wired below. Declared here so the job
+  // recorders can refresh presence with the live job set as jobs start/end.
+  /** @type {import('./work-channel.mjs').WorkChannel | null} */
+  let workChannel = null;
+  // Maintain `activeJobs` unconditionally: it feeds both the supervisor activity
+  // file (gated inside writeActivity) AND the agentic presence frame's live
+  // jobKey set, so a standalone worker (no NANO_SUPERVISOR_ACTIVITY_FILE) still
+  // reports its current jobs on the visibility page.
   const recordJobStart = (job, jobType) => {
-    if (!activityFile) return;
     activeJobs.set(String(job.jobKey), { type: jobType, since: Date.now() });
     writeActivity();
+    workChannel?.refreshPresence();
   };
   const recordJobEnd = (job) => {
-    if (!activityFile) return;
     activeJobs.delete(String(job.jobKey));
     writeActivity();
+    workChannel?.refreshPresence();
   };
   // Seed an initial idle marker so status reports 'idle' immediately after spawn.
   writeActivity();
 
+  // ---- Agentic visibility channel (ADR 0056 — slice C2, #41) ----------------
+  // Connect this worker to the app's same-port `/agentic` channel and announce
+  // presence (identity, host, live jobs), heartbeat, and deregister on exit, so
+  // it appears live on the Workforce visibility page. This is the SINGLE place
+  // the connected+authenticated channel client is instantiated in `work`: the
+  // sibling slices C3 (PTY relay, #42) and C4 (buffer, #43) attach to the
+  // 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).
+  const agenticCfg = resolveAgenticConfig();
+  if (agenticCfg) {
+    try {
+      workChannel = await createWorkChannel({
+        instance: workerName,
+        host: hostname(),
+        capability: {
+          cognition: profile.rank,
+          family: profile.model || undefined,
+          host: hostname(),
+        },
+        listJobKeys: () => [...activeJobs.keys()],
+        url: agenticCfg.url,
+        token: agenticCfg.token,
+        credential: agenticCfg.credential,
+        logger,
+      });
+      const shown = redactAgenticUrl(buildAgenticUrl(agenticCfg.url, {}));
+      logger.info(`  agentic channel: announcing presence as ${workerName} on ${shown}`);
+    } catch (err) {
+      // Never let a channel failure stop the worker from doing its actual job.
+      workChannel = null;
+      logger.warn(`  agentic channel unavailable (${err?.message || err}); continuing without visibility.`);
+    }
+  } else {
+    logger.info('  agentic channel: not enrolled (set NANO_AGENTIC_URL + NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL to appear on the visibility page).');
+  }
+
   // A per-job-type worker factory. Captures all the CLI-local + profile context
   // in closure scope so the profile watcher below can (re)spawn a poller for any
   // job type on demand without re-reading the flags.
@@ -3865,6 +3939,17 @@ async function workAgent(req, flags) {
       } else {
         logger.info('All workers stopped.');
       }
+      // Deregister from the visibility channel LAST, so the worker disappears
+      // from the page only once its jobs have drained. Best-effort — a channel
+      // teardown must never hang shutdown.
+      if (workChannel) {
+        try {
+          await workChannel.stop(`worker stopped (${signal})`);
+          logger.info('Deregistered from the agentic visibility channel.');
+        } catch (err) {
+          logger.warn(`agentic channel deregister failed: ${err?.message || err}`);
+        }
+      }
       resolve();
     };
     process.once('SIGINT', () => { stop('SIGINT'); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.26.3",
+  "version": "1.28.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -22,6 +22,9 @@
   "files": [
     "c8ctl-plugin.js",
     "platforms.mjs",
+    "agentic.mjs",
+    "agentic-loader-hook.mjs",
+    "work-channel.mjs",
     "nanobpmn-binary.json",
     "README.md"
   ],
@@ -31,7 +34,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.6"
   },
   "c8ctl": {
     "defaults": {
@@ -46,13 +49,17 @@
     "@semantic-release/github": "^12.0.6",
     "semantic-release": "^25.0.3"
   },
+  "dependencies": {
+    "@nanobpm/agentic": "^0.1.0",
+    "@nanobpm/urban-agent-client": "^0.1.0"
+  },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.26.3",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.26.3",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.26.3",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.26.3",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.26.3",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.26.3",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.26.3"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.28.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.28.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.28.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.28.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.28.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.28.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.28.0"
   }
 }

package/work-channel.mjs

@@ -0,0 +1,290 @@
+// The `work` command's agentic-visibility channel seam (ADR 0056 — slice C2,
+// jwulf/c8ctl-plugin-nano#41).
+//
+// This module owns the SINGLE connected + authenticated channel client a
+// running worker (`c8ctl nano work <profile>`) uses to appear on the Workforce
+// visibility page. It is the wave-1 scaffold the sibling slices build on:
+//
+//   - C3 (#42, PTY relay) publishes framed terminal output through the
+//     relay-lane sink exposed by {@link WorkChannel.relayLane}.
+//   - C4 (#43, buffer) subscribes to the connect / disconnect / reconnect
+//     lifecycle events exposed by {@link WorkChannel.onConnect} /
+//     {@link WorkChannel.onDisconnect} / {@link WorkChannel.onReconnect} to
+//     drive its buffer flush at the transport seam.
+//
+// Both siblings EXTEND this holder; neither opens, authenticates, or
+// re-instantiates the channel. The connected client is created in exactly one
+// place — {@link createWorkChannel} — alongside the worker's existing
+// `camunda.createClient()` wiring.
+//
+// Everything on the wire (frame codec, lanes, presence payloads) is CONSUMED
+// through this plugin's single import surface (`./agentic.mjs`), which in turn
+// consumes `@nanobpm/agentic` + `@nanobpm/urban-agent-client`. Nothing is
+// re-declared here.
+//
+// SCOPE (C2): presence + the shared seam only. Capability→SERVE-token
+// resolution (REGISTER/SERVE enrolment) is the separate epic #58 and is NOT
+// done here — the worker announces presence (identity, host, live jobs),
+// heartbeats, and deregisters, and the SERVE handshake is deliberately left
+// disabled (`serveTimeoutMs: 0`, the announce is fire-and-forget).
+
+import { loadAgenticClient } from './agentic.mjs';
+
+const DEFAULT_HEARTBEAT_MS = 10_000;
+// Outbound ring size (frames) the client buffers while the hub is unreachable.
+// C4 (#43) tunes/uses this seam; a sensible default keeps a worker that starts
+// before the app from losing its early presence/relay frames.
+const DEFAULT_BUFFER_CAPACITY = 1024;
+
+/**
+ * Build the worker's agentic-channel WebSocket URL from the app's HTTP base URL
+ * plus the ADR 0028 identity token and capability credential, carried as query
+ * params — the same `?token=…` pattern the blackboard hook uses (and exactly
+ * what `sharedSecretAuthenticator` reads on the hub side). `http`→`ws`,
+ * `https`→`wss`; the channel is served same-port at `/agentic`.
+ *
+ * @param {string} baseUrl the app's own HTTP(S) base URL, e.g. `http://localhost:8080`
+ * @param {{ token: string, credential: string, path?: string }} auth
+ * @returns {string} the `ws(s)://…/agentic?token=…&capability=…` URL
+ */
+export function buildAgenticUrl(baseUrl, { token, credential, path = '/agentic' } = {}) {
+  if (typeof baseUrl !== 'string' || baseUrl.trim() === '') {
+    throw new Error('buildAgenticUrl requires a non-empty base URL');
+  }
+  const u = new URL(baseUrl);
+  if (u.protocol === 'http:') u.protocol = 'ws:';
+  else if (u.protocol === 'https:') u.protocol = 'wss:';
+  else if (u.protocol !== 'ws:' && u.protocol !== 'wss:') {
+    throw new Error(`Unsupported agentic base URL protocol "${u.protocol}" (expected http/https/ws/wss)`);
+  }
+  // Preserve any base path, then append the same-port channel path.
+  const basePath = u.pathname.replace(/\/+$/, '');
+  u.pathname = `${basePath}${path}`;
+  if (token !== undefined && token !== null && token !== '') u.searchParams.set('token', String(token));
+  if (credential !== undefined && credential !== null && credential !== '') {
+    u.searchParams.set('capability', String(credential));
+  }
+  return u.toString();
+}
+
+/**
+ * Redact the token/capability query params from a channel URL for logging.
+ * @param {string} url
+ * @returns {string}
+ */
+export function redactAgenticUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.searchParams.has('token')) u.searchParams.set('token', '***');
+    if (u.searchParams.has('capability')) u.searchParams.set('capability', '***');
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Normalise a capability object for the `register` presence frame. Drops
+ * undefined/empty attributes so the enrolment attribute stays minimal, and
+ * carries the worker's live `jobs` (jobKeys) as a forward-compatible nested
+ * field — the S0 register validator only requires `capability` to be an object
+ * and ignores extra fields ("a later slice may enrich a payload without
+ * breaking older peers"), so the visibility page can surface `capability.jobs`
+ * without any wire-contract change.
+ *
+ * @param {{ cognition?: string, weight?: number, family?: string, host?: string }} capability
+ * @param {readonly string[]} jobs
+ * @returns {object}
+ */
+function presenceCapability(capability, jobs) {
+  const out = {};
+  if (capability) {
+    if (typeof capability.cognition === 'string' && capability.cognition !== '') out.cognition = capability.cognition;
+    if (typeof capability.weight === 'number' && Number.isFinite(capability.weight)) out.weight = capability.weight;
+    if (typeof capability.family === 'string' && capability.family !== '') out.family = capability.family;
+    if (typeof capability.host === 'string' && capability.host !== '') out.host = capability.host;
+  }
+  out.jobs = Array.isArray(jobs) ? jobs.map(String) : [];
+  return out;
+}
+
+/**
+ * @typedef {object} WorkChannel
+ * @property {import('@nanobpm/urban-agent-client').AgenticClient} client the one connected channel client
+ * @property {() => void} refreshPresence re-announce presence (call when the live job set changes)
+ * @property {() => { relay: (stream: string, chunk: string) => void }} relayLane C3's relay-lane sink accessor
+ * @property {(fn: () => void) => () => void} onConnect subscribe to the first successful connect
+ * @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 {() => number} buffered outbound frames currently buffered awaiting the channel
+ * @property {(reason?: string) => Promise<void>} stop deregister + close cleanly
+ */
+
+/**
+ * Create the worker's single connected + authenticated agentic channel client
+ * and announce presence. The connection begins immediately; because the client
+ * buffers outbound frames, presence is announced (and relay is usable) even
+ * before the socket is open — it drains on connect.
+ *
+ * This is the ONLY place the channel client is instantiated in `work`. Sibling
+ * slices consume the accessors on the returned holder; they do not connect.
+ *
+ * @param {object} opts
+ * @param {string} opts.instance stable worker instance id (the worker name) carried on every presence frame
+ * @param {string} opts.host the worker's host label
+ * @param {{ cognition?: string, weight?: number, family?: string, host?: string }} [opts.capability] declared enrolment capability
+ * @param {() => readonly string[]} [opts.listJobKeys] reads the live jobKey set from the worker's activeJobs map
+ * @param {string} opts.url the app's HTTP(S) base URL (the channel is served same-port at `/agentic`)
+ * @param {string} opts.token ADR 0028 identity token
+ * @param {string} opts.credential capability credential
+ * @param {number} [opts.heartbeatIntervalMs] presence heartbeat cadence (ms)
+ * @param {number} [opts.bufferCapacity] outbound ring size in frames
+ * @param {import('@nanobpm/urban-agent-client').TransportFactory} [opts.transport] injectable transport (tests)
+ * @param {import('@nanobpm/urban-agent-client').ReconnectOptions} [opts.reconnect] reconnect/backoff policy passthrough
+ * @param {(fn: () => void, ms: number) => void} [opts.schedule] injectable backoff scheduler (tests)
+ * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger] optional logger
+ * @returns {Promise<WorkChannel>}
+ */
+export async function createWorkChannel(opts) {
+  const {
+    instance,
+    host,
+    capability,
+    listJobKeys = () => [],
+    url,
+    token,
+    credential,
+    heartbeatIntervalMs = DEFAULT_HEARTBEAT_MS,
+    bufferCapacity = DEFAULT_BUFFER_CAPACITY,
+    transport,
+    reconnect,
+    schedule,
+    logger,
+  } = opts || {};
+
+  if (typeof instance !== 'string' || instance.trim() === '') {
+    throw new Error('createWorkChannel requires a non-empty instance id');
+  }
+  if (typeof url !== 'string' || url.trim() === '') {
+    throw new Error('createWorkChannel requires an agentic channel base url');
+  }
+
+  const channelUrl = buildAgenticUrl(url, { token, credential });
+  const declaredCapability = { ...(capability || {}) };
+  if (typeof host === 'string' && host !== '' && !declaredCapability.host) {
+    declaredCapability.host = host;
+  }
+
+  const { connectAgenticChannel } = await loadAgenticClient();
+
+  // The single connected client. serveTimeoutMs:0 disables the SERVE handshake
+  // wait — SERVE-token resolution is the enrolment epic (#58), out of scope for
+  // C2; we only need presence to land, which the REGISTER frame does on its own.
+  const client = connectAgenticChannel({
+    url: channelUrl,
+    instance,
+    heartbeatIntervalMs,
+    serveTimeoutMs: 0,
+    bufferCapacity,
+    ...(transport ? { transport } : {}),
+    ...(reconnect ? { reconnect } : {}),
+    ...(schedule ? { schedule } : {}),
+  });
+
+  const log = logger || {};
+
+  /** (Re)announce presence with the current live job set. Fire-and-forget: the
+   * REGISTER frame is what makes the worker appear; the returned promise only
+   * resolves on a SERVE (disabled here), so we never await it and swallow its
+   * rejection so a missing SERVE is not an unhandled rejection. */
+  const refreshPresence = () => {
+    let jobs = [];
+    try {
+      jobs = listJobKeys() || [];
+    } catch {
+      jobs = [];
+    }
+    const cap = presenceCapability(declaredCapability, jobs);
+    // register() enqueues the frame even while the channel is down (it drains on
+    // connect); catch guards the deliberately-never-resolving SERVE promise.
+    Promise.resolve(client.register({ capability: cap })).catch(() => {});
+  };
+
+  // Lifecycle fan-out: the client fires onOpen on the first connect AND on every
+  // reconnect. Split that into a one-shot "connect" and a repeated "reconnect"
+  // so C4 can distinguish the initial attach from a recovery flush.
+  let hasConnected = false;
+  const connectListeners = new Set();
+  const reconnectListeners = new Set();
+  const disconnectListeners = new Set();
+  const fan = (set, arg) => {
+    for (const fn of set) {
+      try {
+        fn(arg);
+      } catch (err) {
+        try {
+          log.warn?.(`work-channel listener threw: ${err?.message || err}`);
+        } catch {
+          /* never let a listener failure escape the lifecycle dispatch */
+        }
+      }
+    }
+  };
+
+  client.onOpen(() => {
+    if (!hasConnected) {
+      hasConnected = true;
+      fan(connectListeners);
+      // The presence announce buffered before connect drains on this first open,
+      // so no re-announce is needed here — avoid a redundant duplicate register.
+    } else {
+      fan(reconnectListeners);
+      // Re-announce presence on RECONNECT so the durable presence row reflects
+      // this worker's current identity/host/jobs after a hub restart/outage.
+      refreshPresence();
+    }
+  });
+  client.onClose((info) => {
+    fan(disconnectListeners, info);
+  });
+
+  // Announce presence immediately; the frame buffers and drains on connect.
+  refreshPresence();
+
+  const subscribe = (set) => (fn) => {
+    if (typeof fn !== 'function') return () => {};
+    set.add(fn);
+    return () => set.delete(fn);
+  };
+
+  /** @type {WorkChannel} */
+  const channel = {
+    client,
+    refreshPresence,
+    // C3 (#42): the relay-lane sink. Delegates to the one connected client so
+    // relay frames ride the shared, buffered, QoS-ordered outbound path.
+    relayLane: () => ({
+      relay: (stream, chunk) => client.relay(stream, chunk),
+    }),
+    onConnect: subscribe(connectListeners),
+    onReconnect: subscribe(reconnectListeners),
+    onDisconnect: subscribe(disconnectListeners),
+    connected: () => client.connected,
+    buffered: () => client.buffered,
+    async stop(reason = 'worker stopped') {
+      try {
+        client.deregister(reason);
+      } catch (err) {
+        try {
+          log.warn?.(`agentic deregister failed: ${err?.message || err}`);
+          client.close();
+        } catch {
+          /* best effort — never let shutdown hang on the channel */
+        }
+      }
+    },
+  };
+
+  return channel;
+}