c8ctl-plugin-nano 1.29.0 → 1.31.0

package/README.md

@@ -219,6 +219,66 @@ name is generated, so two `work reviewer` processes never collide at the
 broker. (`--name` names the worker; the profile to run is always the
 positional argument.)
 
+### Live agent visibility: the `/agentic` channel + live terminals
+
+A running worker can appear **live on the Workforce visibility page** and stream
+its agents' terminals to an operator's cockpit. This rides the app's agentic
+channel (ADR 0056), served **same-port** on the app's own HTTP base URL at path
+**`/agentic`** — not a sidecar, so there's no extra port to open.
+
+**Connecting.** Enrolment is opt-in: a worker only connects when it has both an
+ADR 0028 **identity token** and a **capability credential** (the same `?token=…`
+pattern the blackboard uses). Point it at the app and hand it the two secrets via
+env (or persisted config); the channel URL defaults to the configured nano URL:
+
+```bash
+# Enrol this worker on the app's same-port /agentic channel
+export NANO_AGENTIC_URL=http://localhost:8080     # app base URL; channel is served at /agentic
+export NANO_AGENTIC_TOKEN=<identity-token>         # ADR 0028 identity
+export NANO_AGENTIC_CREDENTIAL=<capability-cred>   # capability credential
+c8ctl nano work reviewer
+#   agentic channel: announcing presence as ‹worker› on ws://localhost:8080/agentic
+```
+
+Without both secrets the worker runs **exactly as before, off the channel** — no
+visibility, no relay, nothing else changes. A valid identity + capability
+connects; an invalid identity is rejected (unauthorized) and a missing capability
+is rejected (forbidden).
+
+**How presence appears.** On connect the worker **announces** its identity, its
+`host`, and the set of `jobKeys` it is currently running, then **heartbeats** to
+stay live and **re-announces** after a reconnect so its row survives a hub
+restart. When `work` stops it **deregisters cleanly**, so the worker disappears
+from the visibility page on exit.
+
+**Opting a role into a live terminal (PTY vs pipe).** Each role chooses whether
+its agent harness runs on a full **PTY** (a real terminal — streamed on the relay
+lane and **steerable**: an operator's keystrokes reach the running agent) or a
+plain **pipe** (streamed, not interactive). It's a **per-role opt-in**, set on
+the hire profile and defaulting to `pipe`:
+
+```bash
+# Hire a role whose harness runs on a full, steerable PTY
+c8ctl nano hire --name coder --rank senior --command copilot --terminal pty
+
+# Override the mode for a one-off worker without re-hiring
+NANO_AGENTIC_TERMINAL=pipe c8ctl nano work coder
+```
+
+A PTY needs the optional native `node-pty` dependency; when it is
+**unavailable** (not installed, or Windows) a `pty` role **gracefully falls
+back to a pipe** that still relays. (If `node-pty` is present but a PTY can't be
+spawned at runtime, that job fails rather than falling back.) Each job's terminal
+streams on its own relay stream
+named `job:‹jobKey›`, so output and steer-in are routed from the `jobKey` alone.
+
+**Surviving a hub outage.** A worker that starts **before** the app, or survives
+a **hub restart**, buffers its outbound frames in a **bounded** local ring and
+**drains them in order** on reconnect (no loss or reorder within the bound). The
+bound is operator-tunable for a long expected outage; raise it with
+`NANO_AGENTIC_BUFFER_CAPACITY` (frames). When the bound is hit the worker warns
+rather than silently shedding.
+
 ### Live profile reload (no restart on `assign`)
 
 A running `c8ctl nano work <name>` **watches** the profile it is servicing. When
@@ -332,8 +392,32 @@ composed in FEEL, a task may supply per-instance context via **`task.appendPromp
 separator/preamble), so a null/empty append leaves the base untouched. This lets the
 static prompt live in a model header/side-car while the dynamic tail (e.g. plan-revision
 feedback, a per-task brief) is built per instance.
+
+**Live prompts via linked resources.** A service task can declare a Zeebe/Camunda-parity
+**linked resource** for its prompt instead of baking it into a model header:
+
+```xml
+<zeebe:linkedResources>
+  <zeebe:linkedResource resourceId="plan.md" bindingType="latest" linkName="prompt"/>
+</zeebe:linkedResources>
+```
+
+At job activation the engine resolves the `resourceId` to the **latest** deployed key and
+delivers a `linkedResources` custom header (`[{resourceKey, resourceType, linkName}]`). The
+header carries the **key, not the content** — the worker fetches the bytes over the broker
+REST API (`GET /v2/resources/{resourceKey}/content/binary`, reusing the same nano endpoint
+the worker already talks to; override with `NANO_REST_URL`/`NANO_REST_TOKEN`) and uses the
+UTF-8 content as the **base prompt**. The entry whose `linkName` is `prompt` wins over the
+header-baked `task.prompt` chain; `appendPrompt` still composes onto it. Redeploying just
+the resource updates the prompt for the **next activation** — no process redeploy, no
+worker restart. Jobs without `linkedResources` behave exactly as before (fallback chain).
+A declared prompt resource that can't be fetched **fails the job** (retryable provisioning
+error) rather than running an agent with an empty prompt, and the resolved `resourceKey` is
+logged and echoed on the output envelope as `promptResourceKey` for audit (the engine keeps
+only `latest`, so the key is the reproducibility handle).
+
 On completion the plugin writes an **output envelope** back under
-`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error}`). When a repository was
+`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error, promptResourceKey?}`). When a repository was
 provisioned (below) it also carries `{repository, branch, baseSha, headSha, commits[], pushed, pushError?, gitError?, pr?}`.
 
 **Git provisioning (host).** When `--sandbox none` (the default) and the envelope

package/c8ctl-plugin.js

@@ -59,6 +59,7 @@ 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));
@@ -2071,6 +2072,15 @@ function killTree(child) {
 // envelope is written back on the job's completion variables.
 const AGENT_TASK_NS = 'io.nanobpm.agentTask';
 const AGENT_RESULT_KEY = 'io.nanobpm.agentResult';
+// Zeebe/Camunda-parity linked resources (issue #63). At job activation the
+// engine resolves each declared `<zeebe:linkedResource resourceId … linkName>`
+// to the LATEST deployed key and delivers this custom header: a JSON array of
+// `{ resourceKey, resourceType, linkName }`. The header carries the key, not the
+// content — the worker fetches the bytes over the broker REST API. The entry
+// whose `linkName` matches DEFAULT_PROMPT_LINK_NAME supplies the agent's base
+// prompt (live-updatable by redeploying just the resource).
+const LINKED_RESOURCES_HEADER = 'linkedResources';
+const DEFAULT_PROMPT_LINK_NAME = 'prompt';
 const TASK_ENVELOPE_SCHEMA_VERSION = 1;
 // The result-envelope version is intentionally independent of the task-envelope
 // version so the two contracts can evolve separately without silently coupling.
@@ -2235,7 +2245,13 @@ function collectEnvelopeFrom(source) {
 
 // Normalize the assembled envelope to schema v1, coercing header string values
 // (element templates write everything as strings) into bool/int as needed.
-function normalizeTaskEnvelope(customHeaders, variables) {
+//
+// `opts.basePromptOverride` (issue #63): when a `linkName: prompt` linked
+// resource resolves, its fetched content is passed here and WINS over the
+// header-baked `task.prompt` / `variables.prompt` / `variables.task` chain. The
+// FEEL-composed `appendPrompt` concatenation is unchanged — it still appends to
+// whatever base was resolved.
+function normalizeTaskEnvelope(customHeaders, variables, opts = {}) {
   const raw = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables));
   const str = (v) => (v == null ? undefined : String(v));
   const env = {
@@ -2271,9 +2287,12 @@ function normalizeTaskEnvelope(customHeaders, variables) {
   };
 
   const task = isPlainObject(raw.task) ? raw.task : {};
-  // Base prompt: the reserved `task.prompt` (typically a model header filled at deploy time),
-  // else a plain `prompt`/`task` job variable (the pre-header delivery path).
-  const basePrompt = str(task.prompt) ?? str(variables?.prompt) ?? str(variables?.task);
+  // Base prompt: an override supplied by a resolved `linkName: prompt` linked
+  // resource (issue #63) wins; else the reserved `task.prompt` (typically a model
+  // header filled at deploy time), else a plain `prompt`/`task` job variable (the
+  // pre-header delivery path).
+  const overrideBase = opts && opts.basePromptOverride != null ? String(opts.basePromptOverride) : undefined;
+  const basePrompt = overrideBase ?? str(task.prompt) ?? str(variables?.prompt) ?? str(variables?.task);
   // Verbatim dynamic append: a header-delivered base prompt can't be composed in FEEL, so a task
   // may supply per-instance context (e.g. plan-revision feedback, a per-task brief) via the
   // reserved `task.appendPrompt`, or a plain `appendPrompt` variable. It is concatenated onto the
@@ -2296,7 +2315,133 @@ function normalizeTaskEnvelope(customHeaders, variables) {
   return env;
 }
 
-// ---- Secret resolution (pluggable; only host-env implemented for now) ------
+// ---- Linked resources → live agent prompt (issue #63) ----------------------
+// A job's `linkedResources` activation header carries KEYS (not content); the
+// worker resolves each to the LATEST deployed bytes over the broker REST API, so
+// an agent prompt can be updated by redeploying one Markdown resource — no
+// process redeploy, no harness restart.
+
+// Parse the `linkedResources` custom header off an activated job. The engine
+// delivers a JSON array; element-template/header transport stringifies it. Also
+// tolerate an already-parsed array. Anything malformed/absent → [] (fallback
+// path). Never throws.
+function parseLinkedResources(customHeaders) {
+  if (!isPlainObject(customHeaders)) return [];
+  const raw = customHeaders[LINKED_RESOURCES_HEADER];
+  if (raw == null) return [];
+  let val = raw;
+  if (typeof raw === 'string') {
+    if (!raw.trim()) return [];
+    try { val = JSON.parse(raw); } catch { return []; }
+  }
+  if (!Array.isArray(val)) return [];
+  return val.filter((e) => isPlainObject(e) && e.resourceKey != null);
+}
+
+// Select the linked resource that supplies the base prompt: the first entry
+// whose `linkName` matches (default `prompt`). Returns the entry or null.
+function pickLinkedResource(linkedResources, linkName = DEFAULT_PROMPT_LINK_NAME) {
+  if (!Array.isArray(linkedResources)) return null;
+  return linkedResources.find((e) => isPlainObject(e) && String(e.linkName) === String(linkName)) || null;
+}
+
+// The broker REST base URL + optional bearer the harness uses to fetch resource
+// content — the SAME nano endpoint the worker already talks to (env wins over
+// persisted config, falling back to the default localhost port). A local nano
+// cluster is unauthenticated, so the token is optional; when set (e.g. against a
+// secured gateway) it is sent as a Bearer credential.
+// Same-origin test for two URLs (protocol + host + port). Returns false if
+// either string is missing or unparseable, so a token is never forwarded to an
+// endpoint we can't positively confirm matches.
+function sameOrigin(a, b) {
+  if (!a || !b) return false;
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
+}
+
+function resolveBrokerRestConfig(env = process.env) {
+  // readConfig() swallows parse/IO errors and never throws (returns {}), so no
+  // local try/catch is needed here.
+  const cfg = readConfig() || {};
+  const baseUrl =
+    env.NANO_REST_URL ||
+    env.NANO_BASE_URL ||
+    cfg.nanoUrl ||
+    DEFAULT_NANO_URL;
+  // An explicit REST token always wins. The agentic identity token is only a
+  // fallback for single-token deployments where the broker REST endpoint IS the
+  // agentic endpoint — so only forward it when the REST base URL is same-origin
+  // as the agentic URL. This prevents leaking the identity token to a different
+  // NANO_REST_URL host when no REST token is set (see resolveAgenticConfig).
+  let token = env.NANO_REST_TOKEN || '';
+  if (!token) {
+    const agenticToken = env.NANO_AGENTIC_TOKEN || cfg.agenticToken || '';
+    const agenticUrl =
+      env.NANO_AGENTIC_URL ||
+      cfg.agenticUrl ||
+      cfg.nanoUrl ||
+      env.NANO_BASE_URL ||
+      DEFAULT_NANO_URL;
+    if (agenticToken && sameOrigin(baseUrl, agenticUrl)) token = agenticToken;
+  }
+  return { baseUrl, token };
+}
+
+// Build the content endpoint. Per issue #63 / nano-bpm #759 the non-binary
+// `/content` variant is deprecated for non-RPA types (Markdown → 406), so the
+// worker always fetches `/content/binary`.
+function resourceContentUrl(baseUrl, resourceKey) {
+  const base = String(baseUrl || '').replace(/\/+$/, '');
+  return `${base}/v2/resources/${encodeURIComponent(String(resourceKey))}/content/binary`;
+}
+
+// Fetch a linked resource's bytes and decode UTF-8. A non-2xx or network error
+// is surfaced as a ProvisionError so the caller fails the job with a clear
+// provisioning message (never runs an agent with a silently-empty prompt).
+async function fetchLinkedResourceContent(resourceKey, opts = {}) {
+  const { baseUrl, token, fetchImpl = fetch, timeoutMs = 15_000 } = opts;
+  const url = resourceContentUrl(baseUrl, resourceKey);
+  const controller = new AbortController();
+  const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  let res;
+  try {
+    const headers = { Accept: 'application/octet-stream' };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    res = await fetchImpl(url, { method: 'GET', headers, signal: controller.signal });
+  } catch (err) {
+    throw new ProvisionError(`prompt resource ${resourceKey} fetch failed: ${err && err.message ? err.message : String(err)}`);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  if (!res || !res.ok) {
+    const status = res ? res.status : '?';
+    throw new ProvisionError(`prompt resource ${resourceKey} fetch failed: HTTP ${status} from ${url}`);
+  }
+  try {
+    return await res.text();
+  } catch (err) {
+    throw new ProvisionError(`prompt resource ${resourceKey} decode failed: ${err && err.message ? err.message : String(err)}`);
+  }
+}
+
+// Resolve the base prompt from a `linkName: prompt` linked resource, if the job
+// declares one. Returns `{ basePrompt, resourceKey }` when a prompt resource is
+// present and fetched, or null when no such entry exists (→ fall back to the
+// header-baked task.prompt chain). Throws a ProvisionError when a declared
+// prompt resource cannot be fetched — a provisioning failure, not a silent
+// empty-prompt run.
+async function resolveLinkedPrompt(customHeaders, opts = {}) {
+  const { linkName = DEFAULT_PROMPT_LINK_NAME, baseUrl, token, fetchImpl, timeoutMs } = opts;
+  const entry = pickLinkedResource(parseLinkedResources(customHeaders), linkName);
+  if (!entry) return null;
+  const resourceKey = entry.resourceKey;
+  const basePrompt = await fetchLinkedResourceContent(resourceKey, { baseUrl, token, fetchImpl, timeoutMs });
+  return { basePrompt, resourceKey, resourceType: entry.resourceType ?? null, linkName: String(linkName) };
+}
+
 // Secrets are referenced by NAME, never by value, in the model. A resolver maps
 // a name → value at run time. The wrapper injects them into the child ENV, so
 // values never appear in argv or `docker inspect`.
@@ -3415,7 +3560,7 @@ function runAgentJob(profile, job, opts = {}) {
 
 // Shape the io.nanobpm.agentResult output envelope. When a repository was
 // provisioned (increment 2a), the `git` block adds branch/commits/push/PR facts.
-function buildResultEnvelope(result, { sandbox, image, git, result: agentResult } = {}) {
+function buildResultEnvelope(result, { sandbox, image, git, result: agentResult, promptResourceKey } = {}) {
   const status = result.ok ? 'completed' : (result.timedOut ? 'timedOut' : 'failed');
   const env = {
     schemaVersion: RESULT_ENVELOPE_SCHEMA_VERSION,
@@ -3429,6 +3574,10 @@ function buildResultEnvelope(result, { sandbox, image, git, result: agentResult
     signal: result.signal ?? null,
     error: result.error ?? null,
   };
+  // Audit (issue #63): record which linked-resource key supplied the base prompt.
+  // The engine only keeps `latest` per resourceId (no pinning), so recording the
+  // resolved key is the only reproducibility handle for which prompt version ran.
+  if (promptResourceKey != null) env.promptResourceKey = String(promptResourceKey);
   // The agent's structured result (as returned via $AGENT_RESULT_FILE / sentinel),
   // preserved verbatim for auditability even when merged into the completion vars.
   if (isPlainObject(agentResult)) env.result = agentResult;
@@ -3457,7 +3606,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();
@@ -3469,7 +3618,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 };
 }
 
 /**
@@ -3678,6 +3833,10 @@ async function workAgent(req, flags) {
   const jobTypes = [...new Set([...matrix, ...extraJobTypes])];
   const camunda = globalThis.c8ctl.createClient();
 
+  // Broker REST endpoint for live linked-resource prompts (issue #63) — the same
+  // nano endpoint this worker already talks to. Resolved once at startup.
+  const restConfig = resolveBrokerRestConfig();
+
   logger.info(`Putting "${name}" [${profile.rank}] to work → ${buildAgentCommandLine(profile.command, effectiveArgs)}`);
   logger.info(`  worker: ${workerName}`);
   logger.info(`  model: ${profile.model || '(none)'}; capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
@@ -3720,6 +3879,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
@@ -3763,6 +3924,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, {}));
@@ -3772,6 +3934,23 @@ 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).');
   }
@@ -3826,9 +4005,33 @@ async function workAgent(req, flags) {
           }
         }
 
+        // Live agent prompt (issue #63): if the job declares a `linkName: prompt`
+        // linked resource, fetch its LATEST deployed content and use it as the
+        // base prompt (it wins over the header-baked task.prompt). A declared
+        // prompt resource that can't be fetched is a provisioning failure — fail
+        // (retryable) rather than run an agent with an empty prompt.
+        let promptResourceKey = null;
+        let basePromptOverride;
+        try {
+          const linked = await resolveLinkedPrompt(job.customHeaders ?? {}, {
+            baseUrl: restConfig.baseUrl,
+            token: restConfig.token,
+          });
+          if (linked) {
+            basePromptOverride = linked.basePrompt;
+            promptResourceKey = linked.resourceKey;
+            logger.info(`[${jobType}] job ${job.jobKey} base prompt from linked resource key ${promptResourceKey} (linkName=${linked.linkName}, ${Buffer.byteLength(String(basePromptOverride), 'utf8')} bytes)`);
+          }
+        } catch (err) {
+          const retries = Math.max(0, (Number(job.retries) || 1) - 1);
+          const msg = err instanceof ProvisionError ? err.message : `prompt resource fetch failed: ${err.message}`;
+          logger.warn(`[${jobType}] job ${job.jobKey} not provisioned — ${msg}; retries left ${retries}`);
+          return job.fail({ errorMessage: msg.slice(0, 2000), retries, retryBackOff: 15_000 });
+        }
+
         // Assemble + normalize the task envelope from headers (defaults) and
         // variables (overrides), then resolve any secrets it references.
-        const envelope = normalizeTaskEnvelope(job.customHeaders ?? {}, job.variables ?? {});
+        const envelope = normalizeTaskEnvelope(job.customHeaders ?? {}, job.variables ?? {}, { basePromptOverride });
         const { resolved, missing, names } = resolveJobSecrets(secretResolver, envelope);
         if (missing.length > 0) {
           const retries = Math.max(0, (Number(job.retries) || 1) - 1);
@@ -3973,7 +4176,7 @@ async function workAgent(req, flags) {
         if (resultDir) { try { rmSync(resultDir, { recursive: true, force: true }); } catch { /* best effort */ } liveRunDirs.delete(resultDir); }
         const resultVars = sanitizeResultVars(rawResult);
 
-        const resultEnvelope = buildResultEnvelope(result, { sandbox, image, git: gitResult, result: rawResult });
+        const resultEnvelope = buildResultEnvelope(result, { sandbox, image, git: gitResult, result: rawResult, promptResourceKey });
         if (result.ok) {
           const gitNote = gitResult
             ? ` [${gitResult.branch ? `branch ${gitResult.branch}` : 'detached HEAD'}: ${gitResult.commits.length} commit(s), ${gitResult.branch ? (gitResult.pushed ? 'pushed' : (gitResult.pushError ? 'push FAILED' : 'not pushed')) : 'no branch to push'}${gitResult.pr?.found ? `, PR #${gitResult.pr.number}` : ''}]`
@@ -4189,6 +4392,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.');
@@ -6863,6 +7070,12 @@ export {
 export {
   normalizeTaskEnvelope,
   collectEnvelopeFrom,
+  parseLinkedResources,
+  pickLinkedResource,
+  resolveBrokerRestConfig,
+  resourceContentUrl,
+  fetchLinkedResourceContent,
+  resolveLinkedPrompt,
   coerceBool,
   coerceInt,
   deepMerge,
@@ -6909,6 +7122,8 @@ export {
   derivePollTimeoutMs,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
+  LINKED_RESOURCES_HEADER,
+  DEFAULT_PROMPT_LINK_NAME,
   RESULT_SENTINEL,
   RESERVED_RESULT_KEYS,
   SANDBOXES,
@@ -6982,9 +7197,11 @@ export const metadata = {
         { command: 'c8ctl nano hire --name coder --rank senior --command copilot --env COPILOT_ENABLE_ALL_TOOLS=1', description: 'Persist a harness startup env var (e.g. permissions) on the profile' },
         { command: 'c8ctl nano hire --list', description: 'List hired agent profiles' },
         { command: 'c8ctl nano hire --name coder --rank senior --command "agent-harness" --sandbox docker --image ghcr.io/acme/agent:1', description: 'Create a profile that runs each job in a throwaway Docker container' },
+        { command: 'c8ctl nano hire --name coder --rank senior --command copilot --terminal pty', description: 'Opt this role into a full, steerable live terminal (PTY) streamed on the agentic relay lane (default: pipe)' },
         { command: 'c8ctl nano assign reviewer code-review,testing', description: 'Grant more capabilities (comma-separated, like hire) to an existing hire — additive; running workers hot-reload it' },
         { command: 'c8ctl nano work reviewer', description: 'Spawn Nano job workers for the "reviewer" profile and poll for work' },
         { command: 'c8ctl nano work coder --sandbox docker --image ghcr.io/acme/agent:1', description: 'Run jobs in isolated containers with disk-hygiene reaping' },
+        { command: 'NANO_AGENTIC_URL=http://localhost:8080 NANO_AGENTIC_TOKEN=<identity-token> NANO_AGENTIC_CREDENTIAL=<capability-cred> c8ctl nano work reviewer', description: 'Enrol the worker on the app\'s same-port /agentic channel so it appears live (presence + relay terminals) on the Workforce visibility page' },
         { command: 'c8ctl nano supervisor start --worker reviewer --worker coder', description: 'Start a detached supervisor managing several workers from one terminal' },
         { command: 'c8ctl nano supervisor', description: 'Attach an interactive console to the supervisor (detach with Ctrl-D, leaving it running)' },
         { command: 'c8ctl nano supervisor status', description: 'List supervised workers (pid, state, serviced job / idle, restarts, uptime) without the console' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -26,6 +26,7 @@
     "agentic-loader-hook.mjs",
     "work-channel.mjs",
     "work-relay.mjs",
+    "work-buffer.mjs",
     "nanobpmn-binary.json",
     "README.md"
   ],
@@ -56,12 +57,12 @@
   },
   "optionalDependencies": {
     "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"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.31.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.31.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.31.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.31.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.31.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.31.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.31.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