c8ctl-plugin-nano 1.30.0 → 1.32.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
@@ -612,7 +696,7 @@ release onto a machine that already has nano installed:
 
 ```bash
 c8ctl nano update          # check npm for a newer release and install it
-c8ctl nano update --check  # only report whether an update is available
+c8ctl nano update --check  # report whether an update is available (no install)
 ```
 
 `update` compares the installed plugin version against the latest published on
@@ -622,6 +706,15 @@ with it. It only ever drives npm — it never touches the private upstream sourc
 so it works for any npm-installed user. After updating, restart any running
 cluster (`c8ctl nano restart`) so it picks up the new binary.
 
+Whenever an update is available, `update` (and `update --check`) also prints a
+**changelog of what changed since the installed release** — the per-version
+"Features" / "Bug Fixes" notes pulled from the plugin's public
+[GitHub Releases](https://github.com/jwulf/c8ctl-plugin-nano/releases) (where
+semantic-release records them). This lookup is best-effort and non-blocking: if
+GitHub is unreachable or rate-limited it degrades to a link to the releases page
+and the update proceeds normally. Set `GH_TOKEN` (or `GITHUB_TOKEN`) to raise the
+unauthenticated API rate limit.
+
 If the plugin is running from a local checkout rather than a global npm install,
 `update` prints the manual command instead of reinstalling in place.
 

package/c8ctl-plugin.js

@@ -2072,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.
@@ -2236,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 = {
@@ -2272,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
@@ -2297,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`.
@@ -3416,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,
@@ -3430,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;
@@ -3685,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)'}`);
@@ -3853,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);
@@ -4000,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}` : ''}]`
@@ -5613,6 +5789,183 @@ function compareSemver(a, b) {
   return 0;
 }
 
+// ---------------------------------------------------------------------------
+// Update changelog. `update --check` (and the pre-pull path of a real update)
+// shows what changed between the installed release and latest. The authoritative
+// source is this plugin's PUBLIC GitHub Releases — semantic-release records the
+// generated notes there (@semantic-release/github). The committed CHANGELOG.md
+// is deliberately NOT maintained (the release config dropped the changelog/git
+// plugins so it never pushes to the protected `main`) and isn't even in the npm
+// `files`, so it can't be the source. Every lookup here is best-effort and
+// non-blocking: any failure (offline, rate-limited, private) degrades to a link,
+// never to a failed `update`.
+// ---------------------------------------------------------------------------
+
+/** `owner/repo` parsed from the plugin package's `repository` field (null if absent). */
+function githubRepoSlug() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(pluginDir, 'package.json'), 'utf8'));
+    const raw = pkg?.repository?.url ?? (typeof pkg?.repository === 'string' ? pkg.repository : '');
+    const m = String(raw).match(/github\.com[/:]([^/\s]+\/[^/\s]+?)(?:\.git)?(?:[/#?].*)?$/i);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Keep only the releases strictly newer than `currentVersion` and no newer than
+ * `latestVersion` (when known), newest-first. Pure over its `releases` input (an
+ * array of GitHub release objects) so it is unit-testable without a network call.
+ */
+function filterReleasesSince(releases, currentVersion, latestVersion) {
+  if (!Array.isArray(releases)) return [];
+  const items = [];
+  for (const r of releases) {
+    if (!r || r.draft || r.prerelease) continue;
+    const tag = r.tag_name || r.name || '';
+    const norm = String(tag).replace(/^v/, '');
+    // Require a plain vX.Y.Z tag: a prerelease/build suffix (e.g. -rc.1, +meta)
+    // must exclude the release rather than be normalised away into the window.
+    if (!/^\d+\.\d+\.\d+$/.test(norm)) continue;
+    const ver = norm;
+    if (!currentVersion || compareSemver(ver, currentVersion) <= 0) continue;
+    if (latestVersion && compareSemver(ver, latestVersion) > 0) continue;
+    items.push({ version: ver, tag, body: r.body || '', url: r.html_url || '' });
+  }
+  items.sort((a, b) => compareSemver(b.version, a.version));
+  return items;
+}
+
+/**
+ * Render one semantic-release release body to tight terminal lines: drop the
+ * redundant `# [x.y.z](…)` header, turn `### Features` into a `Features:` label,
+ * flatten `* **scope:** subject ([abc](url))` bullets to `• scope: subject`
+ * (stripping any `([label](url))` commit/PR link groups and inlining any
+ * remaining `[text](url)` as its text). Returns an array of already-indented lines.
+ */
+function renderReleaseBody(body) {
+  const out = [];
+  for (const line of String(body).split(/\r?\n/)) {
+    if (/^#{1,2}\s+\[?\d+\.\d+\.\d+/.test(line)) continue; // redundant version header
+    const heading = line.match(/^#{2,3}\s+(.*\S)\s*$/);
+    if (heading) {
+      out.push(`    ${heading[1]}:`);
+      continue;
+    }
+    const bullet = line.match(/^\s*[*-]\s+(.*)$/);
+    if (bullet) {
+      let text = bullet[1]
+        .replace(/\s*\(\[[^\]]*\]\([^)]*\)\)/g, '') // ([label](url)) commit/PR link groups
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // inline [text](url) -> text
+        .replace(/\*\*(.*?)\*\*/g, '$1') // **scope** -> scope
+        .replace(/\s+/g, ' ')
+        .trim();
+      if (text) out.push(`      \u2022 ${text}`);
+    }
+  }
+  return out;
+}
+
+/** Cap on release pages walked, so a repo with a huge history can never hang the walk. */
+const RELEASE_PAGE_LIMIT = 20;
+
+/**
+ * True once a page contains a published (non-draft/non-prerelease) vX.Y.Z release
+ * at or below `current`. Because the releases API returns newest-first, everything
+ * after that point is older than the installed version, so the walk can stop.
+ */
+function reachedInstalledRelease(page, current) {
+  if (!current || !Array.isArray(page)) return false;
+  for (const r of page) {
+    if (!r || r.draft || r.prerelease) continue;
+    const norm = String(r.tag_name || r.name || '').replace(/^v/, '');
+    if (!/^\d+\.\d+\.\d+$/.test(norm)) continue;
+    if (compareSemver(norm, current) <= 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Fetch this plugin's GitHub releases newer than `current` (best-effort; null on
+ * any failure). Paginates newest-first, stopping as soon as it reaches the
+ * installed release (or a bounded page cap), so the window stays accurate even
+ * when the installed version is far behind and there are >100 releases since.
+ */
+async function fetchReleaseNotesSince(slug, current, latest, timeoutMs = 5000) {
+  if (!slug) return null;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    const headers = {
+      accept: 'application/vnd.github+json',
+      'user-agent': 'c8ctl-plugin-nano',
+      'x-github-api-version': '2022-11-28',
+    };
+    const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    if (token) headers.authorization = `Bearer ${token}`;
+    try {
+      const all = [];
+      for (let page = 1; page <= RELEASE_PAGE_LIMIT; page++) {
+        const res = await fetch(
+          `https://api.github.com/repos/${slug}/releases?per_page=100&page=${page}`,
+          { headers, redirect: 'follow', signal: ctrl.signal },
+        );
+        if (!res.ok) return null;
+        const arr = await res.json();
+        if (!Array.isArray(arr) || arr.length === 0) break;
+        all.push(...arr);
+        // Newest-first: once we hit the installed release (or a short final
+        // page), everything remaining is older than `current` — stop early.
+        if (arr.length < 100 || reachedInstalledRelease(arr, current)) break;
+      }
+      return filterReleasesSince(all, current, latest);
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Print the changelog between the installed release and `latest`. Best-effort:
+ * on any fetch failure it prints a single line pointing at the releases page and
+ * returns, so it can never block or fail an `update`.
+ */
+async function printChangelogSince(_name, current, latest) {
+  const logger = getLogger();
+  const slug = githubRepoSlug();
+  const releasesUrl = slug ? `https://github.com/${slug}/releases` : null;
+  const releases = await fetchReleaseNotesSince(slug, current, latest);
+
+  if (releases === null) {
+    if (releasesUrl) logger.info(`See what changed: ${releasesUrl}`);
+    logger.info('');
+    return;
+  }
+  if (releases.length === 0) {
+    // Nothing resolved between the two (only a build-metadata bump, or a
+    // degraded resolution: current is null / tags don't match vX.Y.Z). Point
+    // at the releases page so the best-effort feature still leaves a trail.
+    if (releasesUrl) logger.info(`See what changed: ${releasesUrl}`);
+    logger.info('');
+    return;
+  }
+
+  logger.info(`What's changed since v${current ?? '?'}:`);
+  logger.info('');
+  for (const rel of releases) {
+    logger.info(`  v${rel.version}`);
+    const lines = renderReleaseBody(rel.body);
+    if (lines.length === 0) logger.info('      (no notes)');
+    else for (const l of lines) logger.info(l);
+    logger.info('');
+  }
+  if (releasesUrl) logger.info(`Full release notes: ${releasesUrl}`);
+  logger.info('');
+}
+
 /**
  * Resolve how npm must be spawned on the given platform. Spawning `npm`
  * directly is not portable: on Windows npm is a `npm.cmd` shim, so bare
@@ -5745,7 +6098,8 @@ function manualUpdateCommand(name, info) {
   return `  npm install -g ${name}@latest`;
 }
 
-function updatePlugin(req) {
+async function updatePlugin(req) {
+  const logger = getLogger();
   const { name, version: current } = pluginPackage();
 
   // The nano server binary ships with the plugin as its platform package
@@ -5766,44 +6120,47 @@ function updatePlugin(req) {
   const info = pluginInstallInfo();
   const manual = manualUpdateCommand(name, info);
 
-  console.log(`Installed: ${name} v${current ?? '?'}${nanoNote}`);
+  logger.info(`Installed: ${name} v${current ?? '?'}${nanoNote}`);
 
   let latest;
   try {
     latest = npmLatestVersion(name);
   } catch (err) {
-    console.log(`Could not check npm for updates: ${err.message}`);
-    console.log('Pull the latest release manually with:');
-    console.log(manual);
+    logger.info(`Could not check npm for updates: ${err.message}`);
+    logger.info('Pull the latest release manually with:');
+    logger.info(manual);
     return;
   }
-  console.log(`Latest:    ${name} v${latest}  (npm)`);
-  console.log('');
+  logger.info(`Latest:    ${name} v${latest}  (npm)`);
+  logger.info('');
 
   if (current && compareSemver(current, latest) >= 0) {
     if (!nanoBin) {
       // Plugin is current but npm never fetched the matching server binary.
-      console.log('Plugin is current, but the nano server binary is not installed for this platform.');
-      console.log('Provision it by reinstalling the plugin so npm fetches the platform package:');
-      console.log('  c8ctl sync plugin');
+      logger.info('Plugin is current, but the nano server binary is not installed for this platform.');
+      logger.info('Provision it by reinstalling the plugin so npm fetches the platform package:');
+      logger.info('  c8ctl sync plugin');
       return;
     }
-    console.log('Already on the latest release — nothing to do.');
+    logger.info('Already on the latest release — nothing to do.');
     return;
   }
 
-  console.log(`Update available: v${current ?? '?'} -> v${latest}`);
+  logger.info(`Update available: v${current ?? '?'} -> v${latest}`);
+  logger.info('');
+
+  await printChangelogSince(name, current, latest);
 
   if (req.check) {
-    console.log('Run `c8ctl nano update` to pull it (or manually):');
-    console.log(manual);
+    logger.info('Run `c8ctl nano update` to pull it (or manually):');
+    logger.info(manual);
     return;
   }
 
   if (info.mode === 'local') {
-    console.log('This plugin runs from a local checkout, so it cannot self-update in place.');
-    console.log('Update it with:');
-    console.log(manual);
+    logger.info('This plugin runs from a local checkout, so it cannot self-update in place.');
+    logger.info('Update it with:');
+    logger.info(manual);
     return;
   }
 
@@ -5812,8 +6169,8 @@ function updatePlugin(req) {
       ? ['install', `${name}@${latest}`, '--prefix', info.prefix]
       : ['install', '-g', `${name}@${latest}`];
   const where = info.mode === 'managed' ? 'the c8ctl plugin store' : "npm's global prefix";
-  console.log(`Pulling ${name}@${latest} into ${where}...`);
-  console.log('');
+  logger.info(`Pulling ${name}@${latest} into ${where}...`);
+  logger.info('');
   try {
     runNpm(installArgs, { stdio: 'inherit' });
   } catch (err) {
@@ -5830,14 +6187,14 @@ function updatePlugin(req) {
       `npm ${installArgs.join(' ')} failed${code}. ${hint}`,
     );
   }
-  console.log('');
+  logger.info('');
   if (info.mode === 'managed') {
-    console.log(`Updated to v${latest}. The new plugin and bundled nano server load on your next c8ctl command.`);
+    logger.info(`Updated to v${latest}. The new plugin and bundled nano server load on your next c8ctl command.`);
   } else {
-    console.log(`Updated to v${latest}.`);
+    logger.info(`Updated to v${latest}.`);
   }
-  console.log('Restart any running cluster to use the new server binary:');
-  console.log('  c8ctl nano restart');
+  logger.info('Restart any running cluster to use the new server binary:');
+  logger.info('  c8ctl nano restart');
 }
 
 // ---------------------------------------------------------------------------
@@ -6885,6 +7242,7 @@ function parseProcessosRequest(args, flags) {
 export { resolveBinary, findBinary, launcherEnvMarkers };
 export { setConfig, unsetConfig, readConfig, writeConfig, getConfigFile, SETTING_ALIASES };
 export { buildNpmInvocation };
+export { compareSemver, githubRepoSlug, filterReleasesSince, renderReleaseBody };
 export {
   webConsoleUrl,
   consoleLinkLabel,
@@ -6894,6 +7252,12 @@ export {
 export {
   normalizeTaskEnvelope,
   collectEnvelopeFrom,
+  parseLinkedResources,
+  pickLinkedResource,
+  resolveBrokerRestConfig,
+  resourceContentUrl,
+  fetchLinkedResourceContent,
+  resolveLinkedPrompt,
   coerceBool,
   coerceInt,
   deepMerge,
@@ -6940,6 +7304,8 @@ export {
   derivePollTimeoutMs,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
+  LINKED_RESOURCES_HEADER,
+  DEFAULT_PROMPT_LINK_NAME,
   RESULT_SENTINEL,
   RESERVED_RESULT_KEYS,
   SANDBOXES,
@@ -7006,16 +7372,18 @@ export const metadata = {
         { command: 'c8ctl nano set model-dir <path>', description: 'Set the workspace dir (models + workers)' },
         { command: 'c8ctl nano config', description: 'Show current plugin configuration and paths' },
         { command: 'c8ctl nano update', description: 'Pull the latest published nano release (re-installs via npm)' },
-        { command: 'c8ctl nano update --check', description: 'Check whether a newer nano release is available' },
+        { command: 'c8ctl nano update --check', description: 'Check for a newer nano release and show the changelog since the installed version (no install)' },
         { command: 'c8ctl nano hire', description: 'Interactively create a CLI agent worker profile (name, rank, command, model, capabilities)' },
         { command: 'c8ctl nano hire --name reviewer --rank senior --command copilot --model gpt-5 --capabilities code-review,testing', description: 'Create a profile non-interactively' },
         { command: 'c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all', description: 'Hire copilot with a command-line switch (copilot --allow-all)' },
         { 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' },
@@ -7061,7 +7429,7 @@ export const commands = {
       purge: { type: 'boolean', description: 'stop/restart: also delete per-node engine data' },
       force: { type: 'boolean', description: 'start: stop any existing cluster first' },
       workspace: { type: 'boolean', description: 'clean: also delete the workspace (models + workers)' },
-      check: { type: 'boolean', description: 'update: only report whether a new release is available; do not install' },
+      check: { type: 'boolean', description: 'update: report whether a new release is available (with the changelog since the installed version); do not install' },
       binary: { type: 'string', description: 'Path to the nanobpmn server binary' },
       name: { type: 'string', description: 'work/supervisor add: worker name (auto ‹host›-‹profile›-‹random› if omitted); hire/assign: agent profile name' },
       rank: { type: 'string', description: 'hire: agent rank (principal|senior|junior|decider)' },
@@ -7140,7 +7508,7 @@ export const commands = {
             showConfig();
             break;
           case 'update':
-            updatePlugin(req);
+            await updatePlugin(req);
             break;
           case 'hire':
             await hireWorker(req, flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.30.0",
+  "version": "1.32.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -57,12 +57,12 @@
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.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"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.32.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.32.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.32.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.32.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.32.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.32.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.32.0"
   }
 }