c8ctl-plugin-nano 1.27.0 → 1.29.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

@@ -15,6 +15,10 @@
 // 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
@@ -80,14 +84,36 @@ export * as transcript from '@nanobpm/agentic/transcript';
 // (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. The slice that
-// actually opens the channel (C2, #41) awaits it from the code path that runs
-// under the appropriate loader/build.
+// 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
@@ -100,6 +126,7 @@ let clientModulePromise;
  */
 export function loadAgenticClient() {
   if (clientModulePromise === undefined) {
+    ensureClientLoadable();
     clientModulePromise = import('@nanobpm/urban-agent-client');
   }
   return clientModulePromise;

package/c8ctl-plugin.js

@@ -57,6 +57,8 @@ 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';
+import { createRelaySession, roleTerminalMode } from './work-relay.mjs';
 
 const requireFromHere = createRequire(import.meta.url);
 const pluginDir = dirname(fileURLToPath(import.meta.url));
@@ -1513,6 +1515,11 @@ function showConfig() {
 
 const RANKS = ['principal', 'senior', 'junior', 'decider'];
 
+// C3 (#42): a role's live-terminal mode — a full PTY (streamed + steerable) or a
+// plain pipe. Default is `pipe` (the safe non-interactive default); `pty` is
+// opt-in per role because a TTY changes the harness's I/O semantics.
+const TERMINAL_MODES = ['pipe', 'pty'];
+
 /** Normalize a capability list: trim, drop empties, de-dupe, sort (canonical). */
 function normalizeCapabilities(input) {
   const raw = Array.isArray(input)
@@ -1731,6 +1738,10 @@ function normalizeStoredProfile(name, profile) {
   if (CONTAINER_SANDBOXES.has(sandbox) && !image) {
     return { error: `profile "${name}" uses sandbox "${sandbox}" but has no image` };
   }
+  // C3 (#42): live-terminal mode. Tolerant — an unknown/legacy value falls back
+  // to the safe `pipe` default rather than failing the whole profile.
+  const terminalRaw = typeof profile.terminal === 'string' ? profile.terminal.trim().toLowerCase() : '';
+  const terminal = TERMINAL_MODES.includes(terminalRaw) ? terminalRaw : 'pipe';
   return {
     profile: {
       name,
@@ -1741,6 +1752,7 @@ function normalizeStoredProfile(name, profile) {
       capabilities: normalizeCapabilities(profile.capabilities),
       sandbox,
       image,
+      terminal,
       env: normalizeEnvMap(profile.env),
     },
   };
@@ -1858,7 +1870,8 @@ async function hireWorker(req, flags) {
     logger.info('Hired agent profiles:');
     for (const name of names.sort()) {
       const p = hires[name];
-      logger.info(`  ${name}  [${p.rank}]  ${buildAgentCommandLine(p.command, p.args)}  (model: ${p.model || '-'}; caps: ${normalizeCapabilities(p.capabilities).join(', ') || '-'})`);
+      const term = String(p.terminal || '').trim().toLowerCase() === 'pty' ? '; terminal: pty' : '';
+      logger.info(`  ${name}  [${p.rank}]  ${buildAgentCommandLine(p.command, p.args)}  (model: ${p.model || '-'}; caps: ${normalizeCapabilities(p.capabilities).join(', ') || '-'}${term})`);
     }
     logger.info('');
     logger.info('Put one to work with: c8ctl nano work <name>');
@@ -1874,6 +1887,7 @@ async function hireWorker(req, flags) {
   let capabilities = flags?.capabilities !== undefined ? flags.capabilities : undefined;
   let sandbox = flags?.sandbox !== undefined ? String(flags.sandbox).trim().toLowerCase() : undefined;
   let image = flags?.image !== undefined ? String(flags.image).trim() : undefined;
+  let terminal = flags?.terminal !== undefined ? String(flags.terminal).trim().toLowerCase() : undefined;
   // Structured command-line switches appended to the command when spawned, e.g.
   // `--arg --allow-all` for `copilot`. Repeatable; each --arg is one argv token.
   const commandArgs = normalizeArgList(flags?.arg);
@@ -1951,11 +1965,17 @@ async function hireWorker(req, flags) {
   if (capabilities === undefined) capabilities = '';
   if (sandbox === undefined || sandbox === '') sandbox = 'none';
   if (image === undefined) image = '';
+  if (terminal === undefined || terminal === '') terminal = 'pipe';
 
   if (!SANDBOXES.includes(sandbox)) {
     logger.error(`Invalid --sandbox "${sandbox}". Use one of: ${SANDBOXES.join(', ')}`);
     process.exit(1);
   }
+  if (!TERMINAL_MODES.includes(terminal)) {
+    logger.error(`Invalid --terminal "${terminal}". Use one of: ${TERMINAL_MODES.join(', ')}`);
+    process.exit(1);
+  }
+
   if (CONTAINER_SANDBOXES.has(sandbox) && !image) {
     logger.error(`--sandbox ${sandbox} requires --image <ref> (the container image the agent runs in).`);
     process.exit(1);
@@ -1984,6 +2004,7 @@ async function hireWorker(req, flags) {
     capabilities: normalizeCapabilities(capabilities),
     sandbox,
     image: image || '',
+    terminal,
     env: profileEnv,
     createdAt: new Date().toISOString(),
   };
@@ -1995,6 +2016,7 @@ async function hireWorker(req, flags) {
   logger.info(`  capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
   if (profile.args.length > 0) logger.info(`  args: ${profile.args.map(shQuote).join(' ')}`);
   logger.info(`  sandbox: ${profile.sandbox}${CONTAINER_SANDBOXES.has(profile.sandbox) ? ` (image ${profile.image})` : ''}`);
+  logger.info(`  live terminal: ${profile.terminal}${profile.terminal === 'pty' ? ' (streamed + steerable on the relay lane)' : ''}`);
   const envKeys = Object.keys(profile.env);
   if (envKeys.length > 0) logger.info(`  env: ${envKeys.join(', ')}`);
   logger.info(`  job types (${matrix.length}): ${matrix.join('  ')}`);
@@ -2902,7 +2924,7 @@ const MAX_CAPTURE_BYTES = 1_048_576; // 1 MiB per stream
 // Spawn a child, pipe `stdinData`, capture byte-capped stdout/stderr, enforce a
 // timeout (invoking `onTimeout(child)` to tear the child down), and resolve to a
 // uniform result. Used by both the host and container executors.
-function spawnCaptureOneShot({ command, args = [], shell = false, detached = false, cwd, env, stdinData, timeoutMs, idleTimeoutMs, onTimeout, stream = false, streamPrefix = '', onStreamOut, onStreamErr }) {
+function spawnCaptureOneShot({ command, args = [], shell = false, detached = false, cwd, env, stdinData, timeoutMs, idleTimeoutMs, onTimeout, stream = false, streamPrefix = '', onStreamOut, onStreamErr, relayTap = null }) {
   return new Promise((resolve) => {
     let child;
     const stdoutChunks = [];
@@ -2991,6 +3013,7 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
       armIdle();
       const buf = Buffer.isBuffer(d) ? d : Buffer.from(d);
       if (teeOut) teeOut(buf.toString('utf8'), false);
+      if (relayTap && typeof relayTap.onData === 'function') relayTap.onData(buf);
       const remaining = MAX_CAPTURE_BYTES - stdoutBytes;
       if (remaining <= 0) { stdoutTruncated = true; return; }
       if (buf.length > remaining) { stdoutChunks.push(buf.subarray(0, remaining)); stdoutBytes = MAX_CAPTURE_BYTES; stdoutTruncated = true; }
@@ -3000,6 +3023,7 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
       armIdle();
       const buf = Buffer.isBuffer(d) ? d : Buffer.from(d);
       if (teeErr) teeErr(buf.toString('utf8'), false);
+      if (relayTap && typeof relayTap.onData === 'function') relayTap.onData(buf);
       const remaining = MAX_CAPTURE_BYTES - stderrBytes;
       if (remaining <= 0) { stderrTruncated = true; return; }
       if (buf.length > remaining) { stderrChunks.push(buf.subarray(0, remaining)); stderrBytes = MAX_CAPTURE_BYTES; stderrTruncated = true; }
@@ -3014,6 +3038,11 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
     });
 
     child.stdin.on('error', () => {});
+    // C3 (#42): pipe mode is one-shot — the job is written to stdin which is then
+    // closed (below), so there is no open channel to feed later steer-in frames
+    // into. We therefore do NOT attach steer-in here: steer-in requires a PTY
+    // (see spawnCapturePty), where stdin stays open for the life of the child.
+    // Pipe-mode roles still stream their output on the relay lane via the tee.
     try {
       if (stdinData != null) child.stdin.write(stdinData);
       child.stdin.end();
@@ -3021,6 +3050,152 @@ function spawnCaptureOneShot({ command, args = [], shell = false, detached = fal
   });
 }
 
+// ---- PTY capture (C3 #42 — full terminal for roles opted into `terminal: pty`)
+// node-pty is a NATIVE, OPTIONAL dependency: a role that runs its harness on a
+// real PTY needs it, but the vast majority of workers run on plain pipes, and we
+// must never let a missing/failed native build break `npm install` or the test
+// suite on stock Node. It is therefore an optionalDependency, lazily required
+// only when a PTY role actually runs, and memoized. Returns null when it is not
+// installed so the caller can fall back to a pipe.
+let ptyModuleCache; // undefined = not tried; null = unavailable; object = loaded
+function loadPtyModule() {
+  if (ptyModuleCache !== undefined) return ptyModuleCache;
+  try {
+    ptyModuleCache = requireFromHere('node-pty');
+  } catch {
+    ptyModuleCache = null;
+  }
+  return ptyModuleCache;
+}
+
+/**
+ * Whether a real PTY can be allocated on this host: node-pty is installed AND we
+ * are on a POSIX platform (the PTY path spawns `sh -c <commandLine>`, mirroring
+ * the container executor; Windows conpty is out of scope for this slice).
+ */
+function ptyAvailable(ptyFactory) {
+  if (process.platform === 'win32') return false;
+  // An injected factory only counts if it actually looks like a node-pty
+  // factory (has a spawn()); a bad injection degrades to the pipe fallback
+  // rather than routing to the PTY path and failing the job.
+  if (ptyFactory) return typeof ptyFactory.spawn === 'function';
+  return loadPtyModule() != null;
+}
+
+// Spawn the harness on a PTY, capture byte-capped output for the job result,
+// tee every chunk to the relay tap (framed + jobKey-tagged by the caller), and
+// feed steer-in bytes back into the PTY. Same result contract as
+// spawnCaptureOneShot. A PTY merges stdout+stderr into one stream, so stderr is
+// always '' here; that is expected for a live terminal. `ptyFactory` is
+// injectable for tests (defaults to node-pty).
+function spawnCapturePty({ command, args = [], cwd, env, stdinData, timeoutMs, idleTimeoutMs, cols = 120, rows = 30, ptyFactory, relayTap = null, stream = false, streamPrefix = '', onStreamOut }) {
+  return new Promise((resolve) => {
+    const factory = ptyFactory || loadPtyModule();
+    if (!factory || typeof factory.spawn !== 'function') {
+      resolve({ ok: false, exitCode: null, stdout: '', stderr: '', error: 'node-pty is not available; cannot allocate a PTY (install node-pty or use terminal: pipe)', truncated: false, stderrTruncated: false });
+      return;
+    }
+
+    const chunks = [];
+    let bytes = 0;
+    let truncated = false;
+    let settled = false;
+    let timer = null;
+    let idleTimer = null;
+    let detachSteer = null;
+    let term;
+
+    // Live "spy" tee (--stream), line-buffered, mirroring spawnCaptureOneShot.
+    const STREAM_TEE_LINE_CAP = 64 * 1024;
+    let teePartial = '';
+    const teeSink = stream ? (onStreamOut || ((line) => process.stdout.write(`${line}\n`))) : null;
+    const tee = (text, final) => {
+      if (!teeSink) return;
+      teePartial += text;
+      let nl;
+      while ((nl = teePartial.indexOf('\n')) !== -1) {
+        teeSink(`${streamPrefix}${teePartial.slice(0, nl)}`);
+        teePartial = teePartial.slice(nl + 1);
+      }
+      while (teePartial.length >= STREAM_TEE_LINE_CAP) {
+        teeSink(`${streamPrefix}${teePartial.slice(0, STREAM_TEE_LINE_CAP)}`);
+        teePartial = teePartial.slice(STREAM_TEE_LINE_CAP);
+      }
+      if (final && teePartial) { teeSink(`${streamPrefix}${teePartial}`); teePartial = ''; }
+    };
+
+    const killTerm = () => {
+      try { term?.kill(); } catch { /* already gone */ }
+    };
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (idleTimer) clearTimeout(idleTimer);
+      if (detachSteer) { try { detachSteer(); } catch { /* best effort */ } detachSteer = null; }
+      if (teeSink) tee('', true);
+      resolve(result);
+    };
+
+    try {
+      term = factory.spawn(command, args, { name: 'xterm-256color', cols, rows, cwd, env });
+    } catch (err) {
+      finish({ ok: false, exitCode: null, stdout: '', stderr: '', error: `pty spawn failed: ${err?.message || err}`, truncated: false, stderrTruncated: false });
+      return;
+    }
+
+    timer = timeoutMs && timeoutMs > 0
+      ? setTimeout(() => {
+          killTerm();
+          finish({ ok: false, exitCode: null, stdout: joinCapped(chunks), stderr: '', error: `timed out after ${timeoutMs}ms`, timedOut: true, truncated, stderrTruncated: false });
+        }, timeoutMs)
+      : null;
+
+    const armIdle = () => {
+      if (settled) return;
+      if (!(idleTimeoutMs && idleTimeoutMs > 0)) return;
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        killTerm();
+        finish({ ok: false, exitCode: null, stdout: joinCapped(chunks), stderr: '', error: `no output for ${idleTimeoutMs}ms (idle)`, timedOut: true, idle: true, truncated, stderrTruncated: false });
+      }, idleTimeoutMs);
+    };
+    armIdle();
+
+    term.onData((d) => {
+      armIdle();
+      const buf = Buffer.isBuffer(d) ? d : Buffer.from(String(d), 'utf8');
+      if (teeSink) tee(buf.toString('utf8'), false);
+      if (relayTap && typeof relayTap.onData === 'function') relayTap.onData(buf);
+      const remaining = MAX_CAPTURE_BYTES - bytes;
+      if (remaining <= 0) { truncated = true; return; }
+      if (buf.length > remaining) { chunks.push(buf.subarray(0, remaining)); bytes = MAX_CAPTURE_BYTES; truncated = true; }
+      else { chunks.push(buf); bytes += buf.length; }
+    });
+
+    term.onExit(({ exitCode, signal }) => {
+      finish({ ok: exitCode === 0, exitCode: typeof exitCode === 'number' ? exitCode : null, signal: signal || null, stdout: joinCapped(chunks), stderr: '', truncated, stderrTruncated: false });
+    });
+
+    // Steer-in: write cockpit bytes straight into the PTY so an operator can
+    // drive the running agent.
+    if (relayTap && typeof relayTap.attachSteer === 'function') {
+      detachSteer = relayTap.attachSteer((data) => {
+        try { term.write(typeof data === 'string' ? data : Buffer.from(data).toString('utf8')); } catch { /* term gone */ }
+      });
+    }
+
+    // Deliver the task envelope on the PTY, then an EOT (Ctrl-D) so a harness
+    // that reads its payload from stdin sees an end-of-input, while the PTY
+    // itself stays open for interactive steer-in.
+    try {
+      if (stdinData != null) term.write(String(stdinData));
+      term.write('\x04');
+    } catch { /* onExit resolves on failure */ }
+  });
+}
+
 function buildAgentPayload(profile, job, envelope) {
   const variables = job.variables && typeof job.variables === 'object' ? job.variables : {};
   return {
@@ -3100,7 +3275,7 @@ function startLockExtender(job, windowMs, intervalMs, tag, logger) {
  * Both paths resolve to the same result contract.
  */
 function runAgentJob(profile, job, opts = {}) {
-  const { timeoutMs, idleTimeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr, args: commandArgs } = opts;
+  const { timeoutMs, idleTimeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr, args: commandArgs, terminal = 'pipe', relaySession = null, ptyFactory } = opts;
   const payload = JSON.stringify(buildAgentPayload(profile, job, envelope));
   const agentEnv = baseAgentEnv(profile, job);
   // The harness command line: the profile command plus its structured switches
@@ -3113,6 +3288,16 @@ function runAgentJob(profile, job, opts = {}) {
   // resolved secrets are layered on top so user env can never shadow them.
   const staticEnv = { ...normalizeEnvMap(profileEnv), ...normalizeEnvMap(envelope?.setup?.env) };
 
+  // C3 (#42): when a relay session is present, tap the harness terminal onto the
+  // relay lane (framed + tagged with this job's jobKey) and accept steer-in. The
+  // tap is inert when there is no session, preserving legacy behaviour exactly.
+  const relayTap = relaySession
+    ? {
+        onData: (buf) => relaySession.relay(buf),
+        attachSteer: (write) => relaySession.attachSteer(write),
+      }
+    : null;
+
   if (!CONTAINER_SANDBOXES.has(sandbox)) {
     // Host: hand the agent the result file by its real path.
     // Defense in depth: --arg tokens are POSIX single-quoted, which cmd.exe on
@@ -3123,6 +3308,29 @@ function runAgentJob(profile, job, opts = {}) {
       return Promise.resolve({ ok: false, exitCode: null, stdout: '', stderr: '', error: 'command-line args (--arg) are not supported for host execution on Windows; use a container sandbox or bake switches into the command', truncated: false, stderrTruncated: false });
     }
     const resultEnv = resultFile ? { [AGENT_RESULT_FILE_ENV]: resultFile } : {};
+    const harnessEnv = { ...process.env, ...staticEnv, ...secretEnv, ...agentEnv, ...extraEnv, ...resultEnv };
+
+    // A role opted into a full PTY (`terminal: pty`) runs the harness on a real
+    // terminal when one can be allocated — so its live output streams as a true
+    // terminal and cockpit steer-in reaches it. Falls back to a pipe (still
+    // relayed) when node-pty is unavailable or on Windows.
+    if (terminal === 'pty' && ptyAvailable(ptyFactory)) {
+      return spawnCapturePty({
+        command: 'sh',
+        args: ['-c', commandLine],
+        cwd,
+        env: harnessEnv,
+        stdinData: payload,
+        timeoutMs,
+        idleTimeoutMs,
+        ptyFactory,
+        relayTap,
+        stream,
+        streamPrefix,
+        onStreamOut,
+      });
+    }
+
     return spawnCaptureOneShot({
       command: commandLine,
       shell: true,
@@ -3132,7 +3340,7 @@ function runAgentJob(profile, job, opts = {}) {
       cwd,
       // Reserved harness env (AGENT_* + the result-file path) is layered AFTER
       // resolved secrets so a task-supplied secret NAME can never shadow it.
-      env: { ...process.env, ...staticEnv, ...secretEnv, ...agentEnv, ...extraEnv, ...resultEnv },
+      env: harnessEnv,
       stdinData: payload,
       timeoutMs,
       idleTimeoutMs,
@@ -3141,6 +3349,7 @@ function runAgentJob(profile, job, opts = {}) {
       streamPrefix,
       onStreamOut,
       onStreamErr,
+      relayTap,
     });
   }
 
@@ -3196,6 +3405,7 @@ function runAgentJob(profile, job, opts = {}) {
     streamPrefix,
     onStreamOut,
     onStreamErr,
+    relayTap,
     onTimeout: (child) => {
       try { spawnSync(engine, ['rm', '-f', containerName], { timeout: 15_000 }); } catch { /* best effort */ }
       try { killTree(child); } catch { /* best effort */ }
@@ -3236,6 +3446,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 +3716,82 @@ 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).');
+  }
+
+  // C3 (#42): the role's live-terminal mode — a full PTY (streamed on the relay
+  // lane when a relay session exists, steerable) or a plain pipe. Honors the
+  // vocab's per-role opt-in read off the hire profile (`terminal: pty|pipe`),
+  // with an env override for a one-off worker (`NANO_AGENTIC_TERMINAL`). The PTY
+  // itself is allocated locally regardless of enrollment; relay streaming (and
+  // steer-in) only engages when the worker is enrolled on the channel, so
+  // without the channel there's simply no relay tap — the harness still runs on
+  // the chosen local transport.
+  const envTerminal = (process.env.NANO_AGENTIC_TERMINAL || '').trim().toLowerCase();
+  const roleTerminal = (envTerminal === 'pty' || envTerminal === 'pipe')
+    ? envTerminal
+    : roleTerminalMode(profile);
+  if (workChannel) {
+    logger.info(`  live terminal: ${roleTerminal === 'pty' ? 'PTY (streamed + steerable)' : 'pipe (streamed)'} on the relay lane.`);
+  }
+
   // 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.
@@ -3584,6 +3883,19 @@ async function workAgent(req, flags) {
 
         let result;
         let gitResult = null;
+        // C3 (#42): the per-job live-terminal relay session. Streams this job's
+        // harness terminal on the relay lane tagged with its jobKey, and accepts
+        // steer-in. Only when the worker is enrolled on the channel; closed in
+        // the finally so its inbound-frame subscription never leaks across jobs.
+        let relaySession = null;
+        if (workChannel) {
+          try {
+            relaySession = createRelaySession({ channel: workChannel, jobKey: job.jobKey, logger });
+          } catch (err) {
+            relaySession = null;
+            logger.warn(`[${jobType}] job ${job.jobKey}: relay session unavailable (${err?.message || err}); continuing without live terminal.`);
+          }
+        }
         // Private structured-result channel: hand the agent a file (outside any
         // repo clone so it can't be `git add`ed) to write its job-result vars to.
         let resultDir = null;
@@ -3614,6 +3926,11 @@ async function workAgent(req, flags) {
             stream,
             streamPrefix: `[${jobType} ${job.jobKey}] `,
             args: effectiveArgs,
+            // C3 (#42): a full PTY for a role that opted in, else a pipe. Both
+            // stream on the relay lane when a relay session exists (skipped when
+            // relaySession is null); only a PTY is interactively steerable.
+            terminal: roleTerminal,
+            relaySession,
             // Route the --stream tee through c8ctl's output-mode-aware logger so
             // spying never corrupts a structured/JSON output mode.
             onStreamOut: stream ? (line) => logger.info(line) : undefined,
@@ -3642,6 +3959,9 @@ async function workAgent(req, flags) {
           if (isContainer) liveRunIds.delete(runId);
           if (runDir && !keepRuns) { try { rmSync(runDir, { recursive: true, force: true }); } catch { /* best effort */ } }
           if (runDir) liveRunDirs.delete(runDir);
+          // Detach the relay session's inbound-frame subscription so it never
+          // outlives the job or leaks a steer listener across jobs.
+          if (relaySession) { try { relaySession.close(); } catch { /* best effort */ } }
         }
 
         // Read the agent's structured result: the file it wrote, else a stdout
@@ -3865,6 +4185,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'); });
@@ -6553,6 +6884,7 @@ export {
   diskBudgetOk,
   containerEngineAvailable,
   runAgentJob,
+  spawnCapturePty,
   startLockExtender,
   provisionRepo,
   finalizeGit,
@@ -6708,6 +7040,7 @@ export const commands = {
       capabilities: { type: 'string', description: 'hire/assign: comma-separated capability list' },
       sandbox: { type: 'string', description: 'hire/work: execution sandbox none|docker|podman (default none). Containers isolate each job.' },
       image: { type: 'string', description: 'hire/work: container image the agent runs in (required for --sandbox docker|podman)' },
+      terminal: { type: 'string', description: 'hire: live-terminal mode for this role — pty (full terminal, streamed + steerable on the relay lane) or pipe (default). NANO_AGENTIC_TERMINAL overrides at work time.' },
       env: { type: 'string', multiple: true, description: 'hire/work: static env var for the harness as NAME=VALUE (repeatable); persisted on hire, work extends/overrides. E.g. permission toggles.' },
       'secret-resolver': { type: 'string', description: 'work: secret resolver for task secretRefs (host = process env; default host)' },
       'reap-age': { type: 'string', description: 'work: age in ms before a finished agent container or job workspace is reaped (default 3600000)' },
@@ -6879,7 +7212,7 @@ function printUsage() {
   console.log('  c8ctl nano unset <bin|model-dir>');
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
-  console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
+  console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--terminal pty|pipe] [--env NAME=VALUE ...] [--list]');
   console.log('  c8ctl nano assign <profileName> <cap[,cap...]> [--name <n>] [--capabilities <a,b>]');
   console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--recovery-window <ms>] [--idle-timeout <ms>] [--job-timeout <ms>] [--poll-timeout <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
   console.log('  c8ctl nano supervisor [start|status|add|remove|restart|stop|logs|attach] ... (manage many workers from one terminal)');
@@ -6923,6 +7256,7 @@ function printUsage() {
   console.log('  --capabilities <a,b> hire/assign: comma-separated capability list');
   console.log('  --sandbox <s>        hire/work: execution sandbox none|docker|podman (default none)');
   console.log('  --image <ref>        hire/work: container image the agent runs in (required for docker|podman)');
+  console.log('  --terminal <m>       hire: live-terminal mode pty|pipe (default pipe); pty streams a steerable terminal on the relay lane');
   console.log('  --env NAME=VALUE     hire/work: static env var for the harness (repeatable); persisted on hire, work extends/overrides');
   console.log('  --list               hire: list existing agent profiles instead of creating one');
   console.log('  --max-parallel <n>   work: max concurrent jobs per worker (default 1)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -23,6 +23,9 @@
     "c8ctl-plugin.js",
     "platforms.mjs",
     "agentic.mjs",
+    "agentic-loader-hook.mjs",
+    "work-channel.mjs",
+    "work-relay.mjs",
     "nanobpmn-binary.json",
     "README.md"
   ],
@@ -52,12 +55,13 @@
     "@nanobpm/urban-agent-client": "^0.1.0"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.27.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.27.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.27.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.27.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.27.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.27.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.27.0"
+    "node-pty": "^1.0.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.29.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.29.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.29.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.29.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.29.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.29.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.29.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;
+}

package/work-relay.mjs

@@ -0,0 +1,193 @@
+// The `work` command's live-terminal relay seam (ADR 0056 — slice C3,
+// jwulf/c8ctl-plugin-nano#42).
+//
+// This module streams a running agent harness's terminal on the agentic
+// channel's RELAY lane, tagged with the originating `jobKey`, and accepts
+// steer-in: bytes an operator's cockpit sends back on the same relay stream are
+// written into the harness's PTY so the run can be steered live.
+//
+// It BUILDS ON C2's merged channel seam (`work-channel.mjs`): the single
+// connected + authenticated channel client is instantiated once in `workAgent`,
+// and this slice consumes the accessors on that holder — it does NOT open,
+// authenticate, or re-instantiate the channel:
+//
+//   - {@link createRelaySession} publishes framed terminal output through
+//     `channel.relayLane().relay(stream, chunk)` (C2's bulk-lane sink), and
+//     subscribes to inbound relay frames via `channel.client.onFrame` for
+//     steer-in.
+//
+// Everything on the wire (the `relay` message family + its `{ stream, offset,
+// chunk }` payload) is CONSUMED through C2's client — nothing is re-declared
+// here. PTY allocation itself is a local concern (see `openTerminal` /
+// `spawnCapturePty` in the plugin); this module is transport-agnostic and takes
+// a duck-typed terminal handle, so it is unit-testable with a fake terminal and
+// a fake channel.
+
+/** Prefix for a per-job relay stream name. One stream carries a job's terminal. */
+export const RELAY_STREAM_PREFIX = 'job:';
+
+/**
+ * The canonical relay stream name for a job. Both the worker's produced output
+ * frames and the cockpit's steer-in frames ride this one stream, so the two
+ * ends agree on routing from the `jobKey` alone (the `jobKey` is available from
+ * `activateJobs` when the job is activated). Direction distinguishes them: the
+ * worker PRODUCES output frames on it and READS inbound frames on it as steer.
+ *
+ * @param {string|number} jobKey
+ * @returns {string}
+ */
+export function relayStreamName(jobKey) {
+  return `${RELAY_STREAM_PREFIX}${String(jobKey)}`;
+}
+
+/**
+ * Resolve a role's terminal mode — whether the agent harness for this role gets
+ * a full PTY or a plain pipe. Honors the vocab's per-role opt-in: a role may set
+ * `terminal: 'pty' | 'pipe'` (preferred) or the boolean shorthand `pty: true`.
+ * Defaults to `'pipe'` — a pipe is the safe, non-interactive default; a PTY is
+ * opt-in per role because it changes the harness's I/O semantics (a TTY, line
+ * discipline, echo).
+ *
+ * The lookup is deliberately structural so it works whether it is fed a vocab
+ * `VocabRole` (forward-compatible: the schema tolerates extra fields) or this
+ * repo's local role notion (a hire profile).
+ *
+ * @param {{ terminal?: unknown, pty?: unknown } | null | undefined} role
+ * @returns {'pty' | 'pipe'}
+ */
+export function roleTerminalMode(role) {
+  if (role && typeof role === 'object') {
+    const t = role.terminal;
+    if (typeof t === 'string') {
+      const norm = t.trim().toLowerCase();
+      if (norm === 'pty') return 'pty';
+      if (norm === 'pipe') return 'pipe';
+    }
+    if (role.pty === true) return 'pty';
+  }
+  return 'pipe';
+}
+
+/**
+ * Narrow an inbound channel {@link Frame} to the steer-in chunk destined for a
+ * given relay stream, or `null` when it is not one. Consumes the shared `relay`
+ * family payload (`{ stream, offset, chunk }`) — never re-declares it.
+ *
+ * @param {{ family?: unknown, payload?: unknown } | null | undefined} frame
+ * @param {string} stream the relay stream this session listens on
+ * @returns {string | null} the steer bytes (as the payload's `chunk` string), or null
+ */
+export function parseInboundRelayChunk(frame, stream) {
+  if (!frame || frame.family !== 'relay') return null;
+  const payload = frame.payload;
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.stream !== stream) return null;
+  const chunk = payload.chunk;
+  return typeof chunk === 'string' ? chunk : null;
+}
+
+/**
+ * @typedef {object} RelaySession
+ * @property {string} stream the relay stream name (derived from the jobKey)
+ * @property {(chunk: string|Uint8Array) => void} relay publish one framed, jobKey-tagged output chunk on the relay lane
+ * @property {(write: (chunk: string) => void) => (() => void)} attachSteer wire inbound steer bytes for this stream to `write`; returns a detach fn
+ * @property {() => void} close detach any steer subscription
+ */
+
+/**
+ * Create the live-terminal relay session for one job. Ties C2's connected
+ * channel to a single job's terminal:
+ *
+ *   - {@link RelaySession.relay} frames each stdout/PTY chunk and streams it on
+ *     the relay lane tagged with this job's `jobKey` (the stream name), through
+ *     C2's `channel.relayLane()` sink — so it rides the shared, buffered,
+ *     QoS-ordered outbound path (and survives a hub outage via C4's ring).
+ *   - {@link RelaySession.attachSteer} subscribes to inbound relay frames on the
+ *     same stream (via C2's `channel.client.onFrame`) and hands their bytes to a
+ *     writer that feeds the harness's PTY — the operator's steer-in.
+ *
+ * @param {object} opts
+ * @param {import('./work-channel.mjs').WorkChannel} opts.channel the C2 channel holder (NOT re-instantiated)
+ * @param {string|number} opts.jobKey the activated job's key; tags every frame and names the stream
+ * @param {{ warn?: Function, debug?: Function }} [opts.logger]
+ * @returns {RelaySession}
+ */
+export function createRelaySession({ channel, jobKey, logger } = {}) {
+  if (!channel || typeof channel.relayLane !== 'function') {
+    throw new Error('createRelaySession requires a WorkChannel with a relayLane() accessor');
+  }
+  if (jobKey === undefined || jobKey === null || String(jobKey) === '') {
+    throw new Error('createRelaySession requires a jobKey');
+  }
+  const stream = relayStreamName(jobKey);
+  const log = logger || {};
+  // Bind the sink once. C2's relayLane() delegates to the single connected
+  // client, so relay frames coalesce onto the one buffered outbound ring.
+  const sink = channel.relayLane();
+
+  const relay = (chunk) => {
+    if (chunk == null) return;
+    const text = typeof chunk === 'string'
+      ? chunk
+      : Buffer.isBuffer(chunk)
+        ? chunk.toString('utf8')
+        : Buffer.from(chunk).toString('utf8');
+    if (text === '') return;
+    try {
+      sink.relay(stream, text);
+    } catch (err) {
+      try {
+        log.warn?.(`relay produce failed for ${stream}: ${err?.message || err}`);
+      } catch {
+        /* never let a logging failure escape the relay path */
+      }
+    }
+  };
+
+  // Each attachSteer call owns its own subscription + detach fn; close() tears
+  // down every one. Tracking them individually (rather than a single shared
+  // handle) means a second attachSteer can't clobber an earlier subscription's
+  // detach — every returned fn detaches exactly the subscription it created.
+  const activeDetaches = new Set();
+  const attachSteer = (write) => {
+    if (typeof write !== 'function') return () => {};
+    const client = channel.client;
+    if (!client || typeof client.onFrame !== 'function') {
+      // No inbound frame surface (e.g. a channel without a client) — steer is a
+      // no-op rather than a crash; output relay still works.
+      return () => {};
+    }
+    const detachFrame = client.onFrame((frame) => {
+      const chunk = parseInboundRelayChunk(frame, stream);
+      if (chunk === null) return;
+      try {
+        write(chunk);
+      } catch (err) {
+        try {
+          log.warn?.(`steer-in write failed for ${stream}: ${err?.message || err}`);
+        } catch {
+          /* swallow */
+        }
+      }
+    });
+    let detached = false;
+    const detach = () => {
+      if (detached) return;
+      detached = true;
+      activeDetaches.delete(detach);
+      try {
+        detachFrame?.();
+      } catch {
+        /* swallow */
+      }
+    };
+    activeDetaches.add(detach);
+    return detach;
+  };
+
+  const close = () => {
+    for (const detach of [...activeDetaches]) detach();
+  };
+
+  return { stream, relay, attachSteer, close };
+}