c8ctl-plugin-nano 1.28.0 → 1.30.0

package/c8ctl-plugin.js

@@ -58,6 +58,8 @@ 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';
+import { createBufferMonitor, resolveBufferCapacity } from './work-buffer.mjs';
 
 const requireFromHere = createRequire(import.meta.url);
 const pluginDir = dirname(fileURLToPath(import.meta.url));
@@ -1514,6 +1516,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)
@@ -1732,6 +1739,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,
@@ -1742,6 +1753,7 @@ function normalizeStoredProfile(name, profile) {
       capabilities: normalizeCapabilities(profile.capabilities),
       sandbox,
       image,
+      terminal,
       env: normalizeEnvMap(profile.env),
     },
   };
@@ -1859,7 +1871,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>');
@@ -1875,6 +1888,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);
@@ -1952,11 +1966,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);
@@ -1985,6 +2005,7 @@ async function hireWorker(req, flags) {
     capabilities: normalizeCapabilities(capabilities),
     sandbox,
     image: image || '',
+    terminal,
     env: profileEnv,
     createdAt: new Date().toISOString(),
   };
@@ -1996,6 +2017,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('  ')}`);
@@ -2903,7 +2925,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 = [];
@@ -2992,6 +3014,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; }
@@ -3001,6 +3024,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; }
@@ -3015,6 +3039,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();
@@ -3022,6 +3051,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 {
@@ -3101,7 +3276,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
@@ -3114,6 +3289,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
@@ -3124,6 +3309,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,
@@ -3133,7 +3341,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,
@@ -3142,6 +3350,7 @@ function runAgentJob(profile, job, opts = {}) {
       streamPrefix,
       onStreamOut,
       onStreamErr,
+      relayTap,
     });
   }
 
@@ -3197,6 +3406,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 */ }
@@ -3248,7 +3458,7 @@ function buildResultEnvelope(result, { sandbox, image, git, result: agentResult
  * 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}
+ * @returns {{ url: string, token: string, credential: string, bufferCapacity: number } | null}
  */
 function resolveAgenticConfig() {
   const cfg = readConfig();
@@ -3260,7 +3470,13 @@ function resolveAgenticConfig() {
   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 };
+  // 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 };
 }
 
 /**
@@ -3511,6 +3727,8 @@ async function workAgent(req, flags) {
   // recorders can refresh presence with the live job set as jobs start/end.
   /** @type {import('./work-channel.mjs').WorkChannel | null} */
   let workChannel = null;
+  /** @type {import('./work-buffer.mjs').BufferMonitor | null} */
+  let bufferMonitor = 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
@@ -3554,6 +3772,7 @@ async function workAgent(req, flags) {
         url: agenticCfg.url,
         token: agenticCfg.token,
         credential: agenticCfg.credential,
+        bufferCapacity: agenticCfg.bufferCapacity,
         logger,
       });
       const shown = redactAgenticUrl(buildAgenticUrl(agenticCfg.url, {}));
@@ -3563,10 +3782,43 @@ async function workAgent(req, flags) {
       workChannel = null;
       logger.warn(`  agentic channel unavailable (${err?.message || err}); continuing without visibility.`);
     }
+    // C4 (#43): observe the client's built-in outbound buffer across the
+    // channel lifecycle — surface a high-water mark and warn when the bound
+    // is hit so a hub outage that starts shedding frames is never silent. The
+    // monitor is observability-only, so keep it OUTSIDE the channel try/catch:
+    // a monitor failure must never null out a healthy channel and take down
+    // presence/visibility.
+    if (workChannel) {
+      try {
+        bufferMonitor = createBufferMonitor(workChannel, {
+          capacity: agenticCfg.bufferCapacity,
+          logger,
+        });
+      } catch (err) {
+        bufferMonitor = null;
+        logger.warn(`  agentic buffer monitor unavailable (${err?.message || err}); channel presence still active.`);
+      }
+    }
   } 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.
@@ -3658,6 +3910,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;
@@ -3688,6 +3953,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,
@@ -3716,6 +3986,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
@@ -3943,6 +4216,10 @@ async function workAgent(req, flags) {
       // from the page only once its jobs have drained. Best-effort — a channel
       // teardown must never hang shutdown.
       if (workChannel) {
+        // Stop the buffer monitor first so its sampler can't fire mid-teardown.
+        try {
+          bufferMonitor?.stop();
+        } catch { /* best effort */ }
         try {
           await workChannel.stop(`worker stopped (${signal})`);
           logger.info('Deregistered from the agentic visibility channel.');
@@ -6638,6 +6915,7 @@ export {
   diskBudgetOk,
   containerEngineAvailable,
   runAgentJob,
+  spawnCapturePty,
   startLockExtender,
   provisionRepo,
   finalizeGit,
@@ -6793,6 +7071,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)' },
@@ -6964,7 +7243,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)');
@@ -7008,6 +7287,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.28.0",
+  "version": "1.30.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -25,6 +25,8 @@
     "agentic.mjs",
     "agentic-loader-hook.mjs",
     "work-channel.mjs",
+    "work-relay.mjs",
+    "work-buffer.mjs",
     "nanobpmn-binary.json",
     "README.md"
   ],
@@ -54,12 +56,13 @@
     "@nanobpm/urban-agent-client": "^0.1.0"
   },
   "optionalDependencies": {
-    "@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"
+    "node-pty": "^1.0.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.30.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.30.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.30.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.30.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.30.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.30.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.30.0"
   }
 }

package/work-buffer.mjs

@@ -0,0 +1,331 @@
+// The `work` command's hub-down buffer observability + policy layer
+// (ADR 0056 — slice C4, jwulf/c8ctl-plugin-nano#43).
+//
+// C4 makes a running worker survive hub disconnects: while the app hub is
+// unreachable (the worker started before the app, or the hub restarted) the
+// worker keeps producing frames, and they drain — bounded and in order — when
+// the channel comes back.
+//
+// DERIVATION OVER DUPLICATION. The bounded local buffer this slice is about
+// ALREADY exists as the connected client's built-in `OutboundRing` (in
+// `@nanobpm/urban-agent-client`): a QoS-aware, capacity-bounded ring that holds
+// every outbound frame while the socket is down and drains in strict lane
+// priority (control → interactive → bulk, FIFO within a lane) on reconnect,
+// shedding the single least-important frame on overflow. It sits at the
+// TRANSPORT seam — below the lanes — so it captures any lane's frames and is
+// therefore independent of C3's relay producer. We do NOT re-declare a second
+// ring here (that would be a parallel, drift-prone buffer over the same
+// frames); we CONSUME the canonical one through C2's `WorkChannel` seam.
+//
+// What this slice actually adds over C2's client is the two things the built-in
+// ring leaves implicit:
+//
+//   1. The bound is OPERATOR-CONFIGURABLE, not a buried literal — see
+//      {@link resolveBufferCapacity} (wired to `NANO_AGENTIC_BUFFER_CAPACITY`
+//      in `resolveAgenticConfig`), so a long expected outage can be given more
+//      headroom without a code change.
+//   2. The drop/backpressure policy is OBSERVABLE. The client sheds overflow
+//      frames silently (`relay()` returns void; the evicted frame is dropped
+//      inside the ring). {@link createBufferMonitor} turns that silent bound
+//      into a visible signal: it watches the buffer depth across C2's
+//      connect / disconnect / reconnect lifecycle, records a high-water mark
+//      and each outage→flush, and warns when the bound is hit so a hit bound is
+//      never silent data loss.
+//
+// The monitor is driven ENTIRELY by C2's lifecycle events + the client's
+// buffer-drained event; it never opens, authenticates, or re-instantiates the
+// channel, and it never produces frames of its own. It is pure observation over
+// the one connected client.
+
+// The outbound-ring bound (frames) the client buffers while the hub is
+// unreachable. Single-sourced from the transport seam (`work-channel.mjs`),
+// which applies it to the client, so the "falls back to the client default"
+// contract stays accurate from one edit — no drift-prone second literal here.
+import { DEFAULT_BUFFER_CAPACITY } from './work-channel.mjs';
+
+const DEFAULT_SAMPLE_INTERVAL_MS = 1_000;
+
+export { DEFAULT_BUFFER_CAPACITY };
+
+/**
+ * Resolve the outbound-buffer bound (in frames) from an operator-supplied value
+ * with a sane fallback. The bound MUST be a positive integer — the client's
+ * `OutboundRing` throws on a non-positive capacity, so we validate here and fall
+ * back rather than let a typo wedge enrolment. Accepts a number or a numeric
+ * string (env vars arrive as strings).
+ *
+ * @param {unknown} raw the operator value (e.g. `process.env.NANO_AGENTIC_BUFFER_CAPACITY`)
+ * @param {number} [fallback] the default when `raw` is absent/invalid
+ * @returns {number} a positive-integer frame bound
+ */
+export function resolveBufferCapacity(raw, fallback = DEFAULT_BUFFER_CAPACITY) {
+  const base = Number.isInteger(fallback) && fallback > 0 ? fallback : DEFAULT_BUFFER_CAPACITY;
+  if (raw === undefined || raw === null || raw === '') return base;
+  const n = typeof raw === 'number' ? raw : Number(String(raw).trim());
+  if (!Number.isInteger(n) || n < 1) return base;
+  return n;
+}
+
+/**
+ * @typedef {object} BufferHealth
+ * @property {number} capacity the configured frame bound
+ * @property {number} buffered frames currently held awaiting a live channel
+ * @property {boolean} connected whether the channel is currently open
+ * @property {number} highWaterMark the deepest buffer depth observed
+ * @property {number} outages number of times the channel went from up→down (buffering began)
+ * @property {number} reconnects number of times the channel recovered (up again after a drop)
+ * @property {number} flushes number of outage backlogs that fully drained on (re)connect
+ * @property {number} lastFlushFrames backlog size captured at the (re)connect that drove the last flush
+ * @property {number|null} lastFlushAt timestamp (ms) the last flush completed, or null
+ * @property {number} atCapacityEvents times a sample found the buffer at/over its bound (overflow shedding)
+ * @property {boolean} atCapacity whether the last sample was at/over the bound
+ */
+
+/**
+ * @typedef {object} BufferMonitor
+ * @property {() => BufferHealth} health snapshot of the buffer's current health/metrics
+ * @property {() => number} sample take a depth sample now (updates high-water / at-capacity); returns the depth
+ * @property {() => void} stop detach all listeners and stop sampling (idempotent)
+ */
+
+/**
+ * Observe the connected client's built-in outbound buffer across C2's channel
+ * lifecycle and surface its health + the (otherwise silent) drop policy.
+ *
+ * The monitor:
+ *  - reads live depth via `channel.buffered()` (the client's `OutboundRing`
+ *    size) — it does not hold its own buffer;
+ *  - on the FIRST connect and every RECONNECT, captures the backlog about to
+ *    flush (the client fires `onOpen`/our lifecycle listeners BEFORE it pumps
+ *    the ring, so the depth read here is the pre-drain backlog) and, when the
+ *    client's `onDrain` then fires (ring emptied after sending), records the
+ *    completed flush;
+ *  - on DISCONNECT (or immediately, if the worker starts before the app and is
+ *    not connected yet), enters an "outage" and samples depth periodically so a
+ *    growing backlog that hits the bound is noticed and warned about;
+ *  - keeps a high-water mark and an at-capacity counter, warning (once per
+ *    transition into the at-capacity state, to avoid log spam) so operators see
+ *    that the bound is shedding frames.
+ *
+ * @param {import('./work-channel.mjs').WorkChannel} channel the C2 seam holder
+ * @param {object} [opts]
+ * @param {number} [opts.capacity] the configured bound (for health/at-capacity); defaults to DEFAULT_BUFFER_CAPACITY
+ * @param {number} [opts.sampleIntervalMs] periodic depth-sample cadence while in an outage; <=0 disables the timer
+ * @param {{ warn?: Function, info?: Function, debug?: Function }} [opts.logger] optional logger
+ * @param {() => number} [opts.now] injectable clock (tests); defaults to Date.now
+ * @param {{ setInterval: Function, clearInterval: Function }} [opts.timers] injectable timers (tests)
+ * @returns {BufferMonitor}
+ */
+export function createBufferMonitor(channel, opts = {}) {
+  if (!channel || typeof channel.buffered !== 'function') {
+    throw new Error('createBufferMonitor requires a WorkChannel with a buffered() accessor');
+  }
+  const capacity = resolveBufferCapacity(opts.capacity, DEFAULT_BUFFER_CAPACITY);
+  const sampleIntervalMs = Number.isFinite(opts.sampleIntervalMs)
+    ? opts.sampleIntervalMs
+    : DEFAULT_SAMPLE_INTERVAL_MS;
+  const log = opts.logger || {};
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+  const timers = opts.timers || { setInterval, clearInterval };
+
+  const state = {
+    highWaterMark: 0,
+    outages: 0,
+    reconnects: 0,
+    flushes: 0,
+    lastFlushFrames: 0,
+    lastFlushAt: /** @type {number|null} */ (null),
+    atCapacityEvents: 0,
+    atCapacity: false,
+  };
+
+  // `buffering` is true while we believe frames are queued for a hub that is
+  // down — set at disconnect (and at creation if we start disconnected), and
+  // cleared when the outage's backlog finishes flushing (the client's next
+  // onDrain) or when a (re)connect finds nothing was buffered. The client fires
+  // our lifecycle connect/reconnect listeners BEFORE it pumps the ring (and thus
+  // before its buffer-drained event), so settleOnOpen captures the pre-drain
+  // backlog into `outageBacklogPeak` and the subsequent onDrain records it.
+  // `outageBacklogPeak` is the deepest the buffer got during the current
+  // outage — what we report as the flushed frame count.
+  let buffering = false;
+  let outageBacklogPeak = 0;
+  let sampleTimer = null;
+  let stopped = false;
+
+  const depth = () => {
+    try {
+      return Number(channel.buffered()) || 0;
+    } catch {
+      return 0;
+    }
+  };
+
+  /** Take a depth sample: update the high-water mark, the per-outage peak, and
+   * the at-capacity signal. */
+  const sample = () => {
+    const d = depth();
+    if (d > state.highWaterMark) state.highWaterMark = d;
+    if (buffering && d > outageBacklogPeak) outageBacklogPeak = d;
+    const atCap = d >= capacity;
+    if (atCap) {
+      state.atCapacityEvents += 1;
+      if (!state.atCapacity) {
+        // Transition into the at-capacity state — warn ONCE so the operator sees
+        // the bound is full and further low-priority frames may be dropped
+        // (bulk relay before interactive before control), but we don't spam
+        // every sample. We only observe depth, so we don't assert a drop has
+        // already happened: depth can reach capacity before any overflow.
+        try {
+          log.warn?.(
+            `agentic outbound buffer full (${d}/${capacity} frames): the hub is unreachable and further low-priority frames may be dropped until it reconnects. Raise NANO_AGENTIC_BUFFER_CAPACITY for a longer expected outage.`,
+          );
+        } catch {
+          /* a logger failure must never break sampling */
+        }
+      }
+    }
+    state.atCapacity = atCap;
+    return d;
+  };
+
+  const startSampler = () => {
+    if (stopped || sampleTimer !== null || sampleIntervalMs <= 0) return;
+    sampleTimer = timers.setInterval(() => sample(), sampleIntervalMs);
+    // Don't keep the event loop alive just to sample a buffer.
+    if (sampleTimer && typeof sampleTimer.unref === 'function') sampleTimer.unref();
+  };
+  const stopSampler = () => {
+    if (sampleTimer !== null) {
+      timers.clearInterval(sampleTimer);
+      sampleTimer = null;
+    }
+  };
+
+  // Enter an outage: begin (or continue) buffering and start watching depth.
+  const beginOutage = () => {
+    buffering = true;
+    outageBacklogPeak = 0;
+    state.atCapacity = false;
+    startSampler();
+    sample();
+  };
+
+  // A (re)connect happened. The client fires this listener BEFORE it pumps the
+  // ring, so depth() here is the pre-drain backlog (captured below); the
+  // client's onDrain then fires and records the completed flush. If we are still
+  // buffering and the buffer is already empty, the outage carried nothing to
+  // flush — just clear it.
+  const settleOnOpen = () => {
+    stopSampler();
+    // Capture the pre-drain backlog. The client fires our connect/reconnect
+    // listeners BEFORE it pumps the ring (see the module header), so depth()
+    // here is the backlog about to flush. Recording it into the outage peak
+    // makes the flush count (onDrain) reflect the real drained depth even when
+    // no periodic sample happened to catch the peak — under production
+    // timer-based sampling a short outage would otherwise leave the peak at 0
+    // and fall back to 1.
+    const d = depth();
+    if (d > state.highWaterMark) state.highWaterMark = d;
+    if (buffering && d > outageBacklogPeak) outageBacklogPeak = d;
+    if (buffering && d === 0) {
+      buffering = false;
+      outageBacklogPeak = 0;
+    }
+    state.atCapacity = false;
+  };
+
+  const unsub = [];
+
+  // First connect (worker-before-app: the pre-app backlog flushes here too).
+  unsub.push(
+    channel.onConnect(() => {
+      settleOnOpen();
+    }),
+  );
+  // Every recovery after a drop (hub restart / transient outage).
+  unsub.push(
+    channel.onReconnect(() => {
+      state.reconnects += 1;
+      settleOnOpen();
+    }),
+  );
+  // The channel went down: begin (or continue) buffering; sample the backlog as
+  // it grows so a bound hit is noticed even during a long outage.
+  unsub.push(
+    channel.onDisconnect(() => {
+      state.outages += 1;
+      beginOutage();
+    }),
+  );
+  // The client's outbound ring emptied after sending: if we were flushing an
+  // outage backlog, the drain is now complete.
+  if (channel.client && typeof channel.client.onDrain === 'function') {
+    unsub.push(
+      channel.client.onDrain(() => {
+        if (buffering) {
+          state.flushes += 1;
+          state.lastFlushFrames = Math.max(outageBacklogPeak, 1);
+          state.lastFlushAt = now();
+          buffering = false;
+          outageBacklogPeak = 0;
+          stopSampler();
+        }
+      }),
+    );
+  }
+
+  // Worker-before-app: if we're created while the channel is still down, we are
+  // already buffering — start sampling immediately so a pre-connect bound hit is
+  // observed and the first-connect drain is recorded as a flush.
+  let connectedNow = false;
+  try {
+    connectedNow = typeof channel.connected === 'function' ? Boolean(channel.connected()) : false;
+  } catch {
+    connectedNow = false;
+  }
+  if (!connectedNow) {
+    buffering = true;
+    outageBacklogPeak = 0;
+    startSampler();
+    sample();
+  }
+
+  return {
+    health() {
+      return {
+        capacity,
+        buffered: depth(),
+        connected: (() => {
+          try {
+            return typeof channel.connected === 'function' ? Boolean(channel.connected()) : false;
+          } catch {
+            return false;
+          }
+        })(),
+        highWaterMark: state.highWaterMark,
+        outages: state.outages,
+        reconnects: state.reconnects,
+        flushes: state.flushes,
+        lastFlushFrames: state.lastFlushFrames,
+        lastFlushAt: state.lastFlushAt,
+        atCapacityEvents: state.atCapacityEvents,
+        atCapacity: state.atCapacity,
+      };
+    },
+    sample,
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      stopSampler();
+      for (const off of unsub) {
+        try {
+          off?.();
+        } catch {
+          /* best effort */
+        }
+      }
+      unsub.length = 0;
+    },
+  };
+}

package/work-channel.mjs

@@ -36,6 +36,7 @@ const DEFAULT_HEARTBEAT_MS = 10_000;
 // before the app from losing its early presence/relay frames.
 const DEFAULT_BUFFER_CAPACITY = 1024;
 
+export { DEFAULT_BUFFER_CAPACITY };
 /**
  * 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

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 };
+}