c8ctl-plugin-nano 1.35.2 → 1.35.4

package/README.md

@@ -274,13 +274,14 @@ 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 — on by default (local-first).** Nano is designed for local use, so
-visibility is **on by default**. Run a worker against a local app and it appears
-live with **zero configuration** — it joins the channel with a well-known
-localhost token in **LOCAL mode** (no credential). The worker presents this
-token to whatever `NANO_AGENTIC_URL` you point it at; the same-machine
-restriction is enforced by the **hub**, which only honours the well-known LOCAL
-token for local/loopback connections:
+**Connecting — on by default (LAN-first).** Nano is designed to run on a trusted
+network, so visibility is **on by default**. Run a worker against a Nano app and it
+appears live with **zero configuration** — it joins the channel with a well-known
+token in **LOCAL mode** (no secret). The worker presents this token to whatever
+`NANO_AGENTIC_URL` you point it at; the hub honours the well-known LOCAL token from
+**any origin** (matching the open trusted-LAN posture of the engine itself), so a
+worker on another box on the LAN appears live too — exposure is governed by the
+server's bind address, not by a shared secret:
 
 ```bash
 # LOCAL mode (default): appears live with no secrets
@@ -318,24 +319,35 @@ used **verbatim** — so an explicit target always wins, and it's also how you
 disambiguate when several apps are running. `NANO_AGENTIC=off` disables the
 channel entirely and attempts **no** discovery.
 
-**Secure mode (opt-in).** For a shared/remote deployment, enrol the worker with an
-ADR 0028 **identity token** and a **capability credential** (the same `?token=…`
-pattern the blackboard uses). Setting either switches the worker into SECURE mode,
-which requires **both** (fail closed if only one is set):
+**Secure mode (opt-in).** For a deployment where you want the visibility channel
+authenticated (rather than open on the LAN), start the server **and** every worker
+box with the **same** `NANO_AGENTIC_SECRET` — same env-var name, same value on both
+sides (Tab A → Slot A). The worker presents it as its identity token and the hub
+verifies it against its own `NANO_AGENTIC_SECRET`. Setting it switches the worker
+into SECURE mode:
 
 ```bash
-# SECURE mode: real enrolment
+# SECURE mode: same NANO_AGENTIC_SECRET on the server and every worker box
 export NANO_AGENTIC_URL=http://localhost:8080
-export NANO_AGENTIC_TOKEN=<identity-token>         # ADR 0028 identity
-export NANO_AGENTIC_CREDENTIAL=<capability-cred>   # capability credential
+export NANO_AGENTIC_SECRET=<shared-secret>         # must equal the server's NANO_AGENTIC_SECRET
 c8ctl nano work reviewer
 #   agentic channel (secure): announcing presence as ‹worker› on ws://localhost:8080/agentic
 ```
 
+The shared secret can also be **persisted** (via config) as `agenticSecret`, so it
+need not be exported into the environment on every run; env still wins over the
+persisted value.
+
+The legacy `NANO_AGENTIC_TOKEN` env var (and persisted `agenticToken`) is still
+accepted as a **deprecated alias** for the shared secret. The **capability
+credential** (`NANO_AGENTIC_CREDENTIAL`) is no longer required — it was removed from
+the hub contract (it was accept-any, pure friction). It remains **optional** and is
+forwarded only if still configured, for forward-compatibility with a future per-peer
+capability verifier.
+
 To opt out entirely, set `NANO_AGENTIC=off` (or persisted `agentic: false`) — the
 worker then runs with **no visibility, no relay, nothing else changed**. In secure
-mode a valid identity + capability connects; an invalid identity is rejected
-(unauthorized) and a missing capability is rejected (forbidden).
+mode a matching secret connects; a wrong secret is rejected (unauthorized).
 
 **How presence appears.** On connect the worker **announces** its identity, its
 `host`, and the set of `jobKeys` it is currently running, then **heartbeats** to
@@ -1098,6 +1110,53 @@ non-interactive shells, in CI, and when `NO_UPDATE_NOTIFIER` /
 `NANO_NO_UPDATE_NOTIFIER` is set. To update, stop and start ProcessOS again — a
 downloaded binary re-fetches the latest build; a `set bin` binary updates itself.
 
+### Pre-upgrade read-model backup & restore
+
+A schema-changing gateway release can reproject the SQLite read model and, in
+the worst case, silently drop completed process-instance history (root cause and
+durable fix tracked in `nano-bpm#831`). As a safety net, whenever `start`
+downloads a **different** ProcessOS version over an existing cached binary — a
+true upgrade — the launcher first snapshots each per-node read model **before**
+swapping the binary. First installs (no cached copy yet) are not upgrades, so
+they skip the backup.
+
+For every `…/data/node-<i>/` that has a `read-model.sqlite`, the launcher copies
+it — together with its `-wal` sidecar (WAL mode keeps uncheckpointed pages there)
+and `-shm` index, plus the coherent point-in-time set `journal.head` and
+`snapshot.*.bin` — into a `read-model-backups/` subdir under that node, named
+`read-model.pre-upgrade-<oldver>-<timestamp>-<rand>.sqlite` (the `<rand>` token
+keeps two backups that land in the same millisecond from colliding). The backup
+path is logged
+at INFO, and a bounded ring (the last **5** upgrades per node) is retained;
+older sets are pruned. The backup is best-effort: a failure is logged and never
+blocks the upgrade.
+
+To restore a node's read model from a backup (do this while the node is
+stopped):
+
+```bash
+# 1. Stop the cluster so nothing is writing the read model.
+c8ctl nano stop
+
+# 2. Pick the pre-upgrade backup you want to restore (newest shown first).
+NODE=~/Library/Application\ Support/c8ctl-nano/data/node-0   # adjust per platform/node
+ls -t "$NODE/read-model-backups"/read-model.pre-upgrade-*.sqlite
+
+# 3. Replace the live read-model files with the chosen backup set. Remove the
+#    stale WAL/SHM first so SQLite does not replay them over the restored DB.
+STEM="$NODE/read-model-backups/read-model.pre-upgrade-<oldver>-<timestamp>-<rand>"
+rm -f "$NODE/read-model.sqlite" "$NODE/read-model.sqlite-wal" "$NODE/read-model.sqlite-shm"
+cp "$STEM.sqlite" "$NODE/read-model.sqlite"
+[ -f "$STEM.sqlite-wal" ] && cp "$STEM.sqlite-wal" "$NODE/read-model.sqlite-wal"
+
+# 4. Start the cluster again.
+c8ctl nano start
+```
+
+> On Linux the data dir defaults to `~/.local/share/c8ctl-nano/data`, on Windows
+> to `%LOCALAPPDATA%\c8ctl-nano\data` (override the root with `C8CTL_NANO_HOME`).
+
+
 On a successful `start` the summary leads with the landing page:
 
 ```

package/c8ctl-plugin.js

@@ -33,6 +33,8 @@ import {
   existsSync,
   mkdirSync,
   openSync,
+  copyFileSync,
+  statSync,
   readFileSync,
   writeFileSync,
   appendFileSync,
@@ -55,7 +57,7 @@ import { join, isAbsolute, resolve as resolvePath, dirname, basename, sep } from
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
-import { createInterface as createReadline } from 'node:readline';
+import { createInterface as createReadline, cursorTo as rlCursorTo, moveCursor as rlMoveCursor, clearScreenDown as rlClearScreenDown } from 'node:readline';
 import { platformForHost } from './platforms.mjs';
 import { createWorkChannel, redactAgenticUrl, buildAgenticUrl } from './work-channel.mjs';
 import { createRelaySession, roleTerminalMode } from './work-relay.mjs';
@@ -136,13 +138,13 @@ const PROCESSOS_DEFAULT_PORT = 8090;
 const DEFAULT_NANO_URL = 'http://localhost:8080';
 
 // The well-known identity token used for LOCAL agentic visibility (security opt-in). Nano is
-// local-first: on the operator's own machine a `nano work` worker joins the visibility channel with
-// zero configuration, so it presents this constant, well-known localhost token — NOT a secret. The
-// worker does not enforce any loopback restriction itself (it presents this token to whatever
-// NANO_AGENTIC_URL is configured); same-machine gating is enforced by the hub, which only honours
-// this well-known token for local/loopback connections. Kept in lock-step with the hub constant in
-// nanobpm/nano-workforce (`app/agentic/channel.ts` LOCAL_AGENTIC_TOKEN). In secure mode (a real
-// NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL) this is never used.
+// local-first: a `nano work` worker joins the visibility channel with zero configuration, so it
+// presents this constant, well-known LOCAL token — NOT a secret. The worker does not enforce any
+// loopback restriction itself (it presents this token to whatever NANO_AGENTIC_URL is configured);
+// the hub honours this well-known token from any origin (matching the open trusted-LAN posture of
+// the engine itself). Kept in lock-step with the hub constant in nanobpm/nano-workforce
+// (`app/agentic/channel.ts` LOCAL_AGENTIC_TOKEN). In secure mode (a real NANO_AGENTIC_SECRET) this
+// is never used.
 const LOCAL_AGENTIC_TOKEN = 'nano-local';
 
 // Passive update notifier (npm-style): refresh the latest published version
@@ -2397,14 +2399,18 @@ function resolveBrokerRestConfig(env = process.env) {
     env.NANO_BASE_URL ||
     cfg.nanoUrl ||
     DEFAULT_NANO_URL;
-  // An explicit REST token always wins. The agentic identity token is only a
+  // An explicit REST token always wins. The agentic identity secret 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
+  // as the agentic URL. This prevents leaking the identity secret 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 agenticToken = env.NANO_AGENTIC_SECRET
+      || cfg.agenticSecret
+      || env.NANO_AGENTIC_TOKEN
+      || cfg.agenticToken
+      || '';
     const agenticUrl =
       env.NANO_AGENTIC_URL ||
       cfg.agenticUrl ||
@@ -3860,19 +3866,24 @@ function buildResultEnvelope(result, { sandbox, image, git, result: agentResult,
  * Local-first (security opt-in). Nano is designed for local use, so visibility is
  * ON BY DEFAULT:
  *   - LOCAL mode (default): no credentials configured — the worker connects with
- *     the well-known localhost token ({@link LOCAL_AGENTIC_TOKEN}) and no
- *     capability credential, so it appears live with zero configuration (the hub's
- *     matching LOCAL mode accepts it).
- *   - SECURE mode: set NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL (or the
- *     persisted `agenticToken`/`agenticCredential`) — an ADR 0028 identity token
- *     AND a capability credential are then sent (enrolment). If only one is set the
- *     config is incomplete and we stay off (fail closed), returning `null`.
+ *     the well-known LOCAL token ({@link LOCAL_AGENTIC_TOKEN}) and no capability
+ *     credential, so it appears live with zero configuration (the hub honours this
+ *     well-known token from any origin on a trusted LAN).
+ *   - SECURE mode: set NANO_AGENTIC_SECRET — the SAME env var name and value the
+ *     server is started with (Tab A → Slot A). The worker presents it as its
+ *     identity token and the hub verifies it against its own NANO_AGENTIC_SECRET.
+ *     The legacy NANO_AGENTIC_TOKEN name (and persisted `agenticToken`) is still
+ *     accepted as a deprecated alias. The capability credential was removed from
+ *     the hub contract (it was accept-any, pure friction), so NANO_AGENTIC_CREDENTIAL
+ *     is OPTIONAL and forwarded only if still configured; a credential set WITHOUT a
+ *     secret is ignored (LOCAL mode).
  *   - OFF: NANO_AGENTIC=off (or 0/false/no), or persisted `agentic:false`.
  *
  * Env wins over persisted config; the base URL falls back to the configured nano
- * URL (the app's own port). Returns `null` only when disabled or half-configured.
+ * URL (the app's own port) and ultimately DEFAULT_NANO_URL, so it is never empty.
+ * Returns `null` only when disabled (the off-switch).
  *
- * @returns {{ url: string, token: string, credential: string, bufferCapacity: number, secure: boolean } | null}
+ * @returns {{ url: string, token: string, credential: string, bufferCapacity: number, secure: boolean, explicitUrl: boolean } | null}
  */
 function resolveAgenticConfig() {
   const cfg = readConfig();
@@ -3891,8 +3902,16 @@ function resolveAgenticConfig() {
     || cfg.nanoUrl
     || process.env.NANO_BASE_URL
     || DEFAULT_NANO_URL;
-  if (!url) return null;
-  const token = process.env.NANO_AGENTIC_TOKEN || cfg.agenticToken || '';
+  // SECURE-mode shared secret. Named NANO_AGENTIC_SECRET to match the server's env
+  // var EXACTLY (Tab A → Slot A): set the same name + value on the server and every
+  // worker box. The worker presents it as its identity token; the hub verifies it
+  // against its own NANO_AGENTIC_SECRET. NANO_AGENTIC_TOKEN / `agenticToken` remain
+  // as a deprecated alias.
+  const secret = process.env.NANO_AGENTIC_SECRET
+    || cfg.agenticSecret
+    || process.env.NANO_AGENTIC_TOKEN
+    || cfg.agenticToken
+    || '';
   const credential = process.env.NANO_AGENTIC_CREDENTIAL || cfg.agenticCredential || '';
   // Outbound hub-down buffer bound (frames). Operator-tunable (C4, #43) so a
   // long expected outage can be given more headroom; resolveBufferCapacity
@@ -3901,14 +3920,16 @@ function resolveAgenticConfig() {
     process.env.NANO_AGENTIC_BUFFER_CAPACITY ?? cfg.agenticBufferCapacity,
   );
 
-  // SECURE mode: any explicit credential configured means the operator opted into
-  // enrolment — require BOTH halves, fail closed if only one is present.
-  if (token || credential) {
-    if (!token || !credential) return null;
-    return { url, token, credential, bufferCapacity, secure: true, explicitUrl };
+  // SECURE mode: an explicit shared secret means the operator opted into a real
+  // per-peer secret. The capability credential was removed from the hub contract
+  // (accept-any → pure friction), so it is OPTIONAL — forwarded only if still
+  // configured. A credential set without a secret is meaningless and falls through
+  // to LOCAL mode.
+  if (secret) {
+    return { url, token: secret, credential, bufferCapacity, secure: true, explicitUrl };
   }
 
-  // LOCAL mode (default): well-known localhost token, no capability credential.
+  // LOCAL mode (default): well-known token, no capability credential.
   return { url, token: LOCAL_AGENTIC_TOKEN, credential: '', bufferCapacity, secure: false, explicitUrl };
 }
 
@@ -4462,9 +4483,9 @@ async function workAgent(req, flags) {
   // lifecycle events) rather than opening their own connection.
   //
   // Local-first (security opt-in): visibility is ON BY DEFAULT. In LOCAL mode the
-  // worker joins with the well-known localhost token and no credential; SECURE
-  // mode (NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL) sends a real ADR 0028
-  // identity + capability; NANO_AGENTIC=off disables it (see resolveAgenticConfig).
+  // worker joins with the well-known LOCAL token and no credential; SECURE mode
+  // (NANO_AGENTIC_SECRET) sends a real per-peer shared secret as the identity;
+  // NANO_AGENTIC=off disables it (see resolveAgenticConfig).
   const agenticTarget = await resolveAgenticTarget({ logger });
   let agenticCfg = null;
   switch (agenticTarget.status) {
@@ -4482,7 +4503,7 @@ async function workAgent(req, flags) {
       break;
     case 'off':
     default:
-      logger.info('  agentic channel: disabled — either the off-switch is set (NANO_AGENTIC=off or persisted agentic:false), or SECURE mode is half-configured (set BOTH NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL). Clear the off-switch to use default LOCAL visibility.');
+      logger.info('  agentic channel: disabled — the off-switch is set (NANO_AGENTIC=off or persisted agentic:false). Clear it to use default LOCAL visibility.');
       break;
   }
   if (agenticCfg) {
@@ -5081,6 +5102,12 @@ const SUPERVISOR_MAX_FRAME_BYTES = 1 << 20; // 1 MiB
 // live refresh (falling back to the attach-time snapshot + lifecycle events).
 const SUPERVISOR_MONITOR_INTERVAL_MS = 1_000;
 
+// How often an *attached* console re-ages and repaints its pinned status block
+// locally, so UPTIME / job-age advance even while the fleet is quiet and the
+// daemon's change-gated push stays silent (issue #83). Pure client-side; no
+// extra daemon traffic.
+const SUPERVISOR_LIVE_TICK_MS = 5_000;
+
 // The `nano work` flags forwarded verbatim to each spawned child.
 // kind: 'value' → `--flag v`; 'boolean' → `--flag`; 'list' → repeated `--flag v`.
 const WORK_FORWARD_FLAGS = {
@@ -5343,10 +5370,16 @@ function formatDuration(ms) {
 /** Project a live/stored worker record to a status row (pure w.r.t. `now`). */
 function summarizeSupervisorWorker(w, now = Date.now()) {
   const alive = isPidAlive(w.pid);
-  const uptimeMs = alive && w.startedAt ? Math.max(0, now - new Date(w.startedAt).getTime()) : 0;
+  // Absolute base epoch (ms) the worker started, so an attached console can
+  // re-age `uptimeMs` locally on each tick (see reageSupervisorStatus) without
+  // the daemon re-broadcasting. `uptimeMs` is the value at snapshot time; it and
+  // `startedAtMs` are kept in lock-step here so a consumer can use either.
+  const startedAtEpoch = alive && w.startedAt ? new Date(w.startedAt).getTime() : null;
+  const startedAtMs = Number.isFinite(startedAtEpoch) ? startedAtEpoch : null;
+  const uptimeMs = startedAtMs != null ? Math.max(0, now - startedAtMs) : 0;
   // Per-job activity (supervised workers only). Guard on pid so a stale marker
   // left by a previous incarnation can't show a dead job as in-flight.
-  let activity = null; // { state: 'busy'|'idle', jobs: [{ key, type, sinceMs }] }
+  let activity = null; // { state: 'busy'|'idle', jobs: [{ key, type, sinceMs, sinceEpochMs }] }
   if (alive) {
     const act = readWorkerActivity(w.id);
     if (act && act.pid === w.pid) {
@@ -5354,7 +5387,10 @@ function summarizeSupervisorWorker(w, now = Date.now()) {
         ? act.jobs.map((j) => ({
             key: String(j.key),
             type: j.type ?? null,
+            // Both the snapshot-time duration and its absolute base, so the
+            // console can re-age the job cell locally (mirrors uptimeMs above).
             sinceMs: Number.isFinite(j.since) ? Math.max(0, now - j.since) : null,
+            sinceEpochMs: Number.isFinite(j.since) ? j.since : null,
           }))
         : [];
       activity = { state: jobs.length > 0 ? 'busy' : 'idle', jobs };
@@ -5368,6 +5404,7 @@ function summarizeSupervisorWorker(w, now = Date.now()) {
     state: w.stopping ? 'stopping' : alive ? 'running' : 'down',
     restarts: Number(w.restarts) || 0,
     uptimeMs,
+    startedAtMs,
     lastExit: w.lastExit ?? null,
     args: Array.isArray(w.args) ? w.args : [],
     activity,
@@ -5413,6 +5450,132 @@ function supervisorJobCell(w) {
   return `${first.key}${more}${dur}`;
 }
 
+/**
+ * Re-age a supervisor status snapshot to `now`, recomputing the ticking
+ * durations (`uptimeMs`, per-job `sinceMs`) from the absolute base epochs the
+ * daemon includes (`startedAtMs`, `sinceEpochMs`). This lets an attached
+ * console tick UPTIME / job-age locally on its own timer — no re-broadcast —
+ * so a quiet-but-busy fleet's clocks still advance. Pure: returns a new object,
+ * never mutates its input. Workers whose base epoch is absent (an older daemon,
+ * or a down worker with no start) keep their snapshot-time value. Non-array /
+ * non-object shapes pass through untouched, so it is safe on any frame.
+ */
+function reageSupervisorStatus(status, now = Date.now()) {
+  if (!status || typeof status !== 'object') return status;
+  const workers = Array.isArray(status.workers) ? status.workers : null;
+  if (!workers) return status;
+  return {
+    ...status,
+    workers: workers.map((w) => {
+      if (!w || typeof w !== 'object') return w;
+      const uptimeMs =
+        Number.isFinite(w.startedAtMs) ? Math.max(0, now - w.startedAtMs) : w.uptimeMs;
+      let activity = w.activity;
+      if (activity && Array.isArray(activity.jobs)) {
+        activity = {
+          ...activity,
+          jobs: activity.jobs.map((j) =>
+            j && typeof j === 'object' && Number.isFinite(j.sinceEpochMs)
+              ? { ...j, sinceMs: Math.max(0, now - j.sinceEpochMs) }
+              : j,
+          ),
+        };
+      }
+      return { ...w, uptimeMs, activity };
+    }),
+  };
+}
+
+/**
+ * Clamp a line to `width` display columns, appending `…` when it is truncated,
+ * so a pinned in-place status block keeps one logical line per terminal row —
+ * the invariant the console's redraw cursor-math depends on (a wrapped row
+ * would desync the up-count). `width < 1` or a non-finite width is treated as
+ * "no clamp". Pure.
+ */
+function clampToWidth(line, width) {
+  const s = String(line ?? '');
+  if (!Number.isFinite(width) || width < 1 || s.length <= width) return s;
+  if (width === 1) return '…';
+  return s.slice(0, width - 1) + '…';
+}
+
+/**
+ * A pinned in-place status "block" for the attached `supervisor>` console
+ * (issue #83). Instead of appending a fresh table on every change, it keeps a
+ * single block just above the readline prompt and *mutates it in place*:
+ * `status()` / `repaint()` erase the previously-painted rows (cursor up N +
+ * clear-to-end) and redraw, so the table updates without scrolling a new copy
+ * into the backlog. `write()` emits scrolling history (events, command replies)
+ * above the block. Durations are re-aged to `now()` on every paint (see
+ * reageSupervisorStatus) so a ~5s tick advances UPTIME / job-age with no
+ * re-broadcast. On a non-TTY (`isTty === false`) there is no cursor addressing:
+ * `status()` appends the table and `write()` is a plain line — the classic
+ * behavior. Each block line is clamped to the terminal width so one logical
+ * line is exactly one terminal row, keeping the erase cursor-math exact.
+ *
+ * Dependencies are injected (stream, columns getter, prompt refresh, clock) so
+ * the render orchestration is unit-testable against a fake capturing stream.
+ */
+function createSupervisorLiveView({
+  stream,
+  isTty,
+  columns = () => 80,
+  refreshPrompt = () => {},
+  now = () => Date.now(),
+}) {
+  let lastStatus = null;
+  let blockLines = 0; // terminal rows the block currently occupies
+
+  const blockText = () => {
+    if (!lastStatus) return '';
+    const cols = columns();
+    return formatSupervisorStatus(reageSupervisorStatus(lastStatus, now()))
+      .split('\n')
+      .map((l) => clampToWidth(l, cols))
+      .join('\n');
+  };
+
+  // Erase the painted block (if any) + the prompt line, leaving the cursor at
+  // column 0 on the row where the block should restart.
+  const erase = () => {
+    rlCursorTo(stream, 0);
+    if (blockLines > 0) rlMoveCursor(stream, 0, -blockLines);
+    rlClearScreenDown(stream);
+  };
+
+  // Draw the (re-aged) block, then re-render the prompt below it.
+  const draw = () => {
+    const text = blockText();
+    if (text) { stream.write(text + '\n'); blockLines = text.split('\n').length; }
+    else blockLines = 0;
+    refreshPrompt();
+  };
+
+  return {
+    /** New snapshot → mutate the block in place (TTY) or append it (non-TTY). */
+    status(frame) {
+      lastStatus = frame;
+      if (isTty) { erase(); draw(); }
+      else { stream.write('\n'); stream.write(formatSupervisorStatus(reageSupervisorStatus(frame, now())) + '\n'); }
+    },
+    /** Repaint the current snapshot re-aged to now (the ~5s tick / resize). */
+    repaint() { if (isTty && lastStatus) { erase(); draw(); } },
+    /** Scrolling history above the block; a plain append on a non-TTY. */
+    write(text) {
+      const s = String(text);
+      if (!isTty) { stream.write(s + '\n'); return; }
+      erase();
+      stream.write(s + '\n');
+      draw();
+    },
+    /** Rows the block currently occupies (test/inspection). */
+    blockRows() { return blockLines; },
+    /** Whether a snapshot has been received (test/inspection). */
+    hasStatus() { return lastStatus != null; },
+  };
+}
+
 /** Render a supervisor status object as an aligned text table. */
 function formatSupervisorStatus(status) {
   const lines = [];
@@ -6324,13 +6487,27 @@ async function attachSupervisorConsole(state) {
     process.exit(1);
   }
 
-  const out = (s) => process.stdout.write(s + '\n');
+  const outStream = process.stdout;
+  // The pinned in-place block needs cursor addressing; on a non-TTY / dumb
+  // terminal we fall back to the classic append-and-scroll behavior.
+  const isTty = !!outStream.isTTY && process.env.TERM !== 'dumb';
+
+  let rl = null;
+  const termCols = () => (Number.isFinite(outStream.columns) ? outStream.columns : 80);
+  const view = createSupervisorLiveView({
+    stream: outStream,
+    isTty,
+    columns: termCols,
+    refreshPrompt: () => { if (rl) { try { rl.prompt(true); } catch { /* ignore */ } } },
+  });
+  // All scrolling output (intro, events, command replies) goes ABOVE the block.
+  const out = (s) => view.write(s);
+
   out('Attached to nano worker supervisor. Type "help" for commands.');
   out('Detach (leave it running) with "detach" or Ctrl-D; tear it down with "stop".');
   sock.write(encodeFrame({ op: 'attach' }));
 
   let buf = '';
-  let rl = null;
   sock.on('data', (chunk) => {
     buf += chunk;
     const { frames, rest } = decodeFrames(buf);
@@ -6338,8 +6515,9 @@ async function attachSupervisorConsole(state) {
     if (frames.length === 0) return;
     for (const frame of frames) {
       if (frame.type === 'status') {
-        out('');
-        out(formatSupervisorStatus(frame));
+        // Mutate the pinned block in place (TTY) or append (non-TTY) — never a
+        // reprinted table stacking up in the scrollback.
+        view.status(frame);
       } else if (frame.type === 'event') {
         const w = frame.worker;
         if (frame.event === 'worker-start') out(`• worker ${w.id} started (pid ${w.pid}).`);
@@ -6356,18 +6534,37 @@ async function attachSupervisorConsole(state) {
         out(`! ${frame.error}`);
       }
     }
-    // A pushed frame writes straight to stdout, stepping on the readline prompt
-    // and any half-typed command. Re-render the prompt (preserving the input
-    // buffer) so an async live-view refresh doesn't corrupt what the user typed.
-    if (rl) { try { rl.prompt(true); } catch { /* ignore */ } }
+    // Every frame above routes through view.status() or view.write(), each of
+    // which already erases+redraws the pinned block and refreshes the prompt in
+    // TTY mode — so an extra repaint here would just duplicate that work (and
+    // flicker at the ~1s monitor cadence). On a non-TTY there is no block to
+    // redraw, so only nudge the prompt so an async push doesn't leave the input
+    // line half-rendered.
+    if (!isTty && rl) { try { rl.prompt(true); } catch { /* ignore */ } }
   });
 
   rl = createReadline({ input: process.stdin, output: process.stdout, prompt: 'supervisor> ' });
+
+  // Local ~5s tick: re-age the block so UPTIME / job-age advance even when the
+  // fleet is quiet (the daemon's change-gated push stays silent). And reflow the
+  // block on terminal resize so a narrower window re-clamps cleanly.
+  let tickTimer = null;
+  let onResize = null;
+  if (isTty) {
+    tickTimer = setInterval(() => view.repaint(), SUPERVISOR_LIVE_TICK_MS);
+    if (typeof tickTimer.unref === 'function') tickTimer.unref();
+    onResize = () => view.repaint();
+    outStream.on('resize', onResize);
+  }
   rl.prompt();
 
   await new Promise((resolve) => {
     let stopping = false;
-    const finish = () => { try { rl.close(); } catch { /* ignore */ } try { sock.end(); } catch { /* ignore */ } resolve(); };
+    const finish = () => {
+      if (tickTimer) { try { clearInterval(tickTimer); } catch { /* ignore */ } tickTimer = null; }
+      if (onResize) { try { outStream.off('resize', onResize); } catch { /* ignore */ } onResize = null; }
+      try { rl.close(); } catch { /* ignore */ } try { sock.end(); } catch { /* ignore */ } resolve();
+    };
 
     sock.on('close', () => { if (!stopping) out('\nSupervisor connection closed.'); finish(); });
 
@@ -7304,6 +7501,158 @@ async function downloadProcessosBinary(url, dest) {
   return dest;
 }
 
+// --- Pre-upgrade read-model backup -----------------------------------------
+// A schema-changing gateway release can reproject the SQLite read model and
+// silently drop completed process-instance history (see nano-bpm#831). Until
+// the engine ships non-destructive migrations, the launcher is the last line of
+// defence: before we swap the binary for a different version, snapshot each
+// per-node read model so the pre-upgrade state is always recoverable.
+
+/** How many prior pre-upgrade backups to keep per node (bounds disk use). */
+const READ_MODEL_BACKUP_RING = 5;
+
+/** Filesystem-safe tag for the version being replaced (for the backup name). */
+function sanitizeVersionTag(v) {
+  const s = String(v ?? '').trim() || 'unknown';
+  return s.replace(/[^A-Za-z0-9._-]+/g, '-');
+}
+
+/**
+ * Copy `src` to `dest` when it exists; best-effort (sidecars may be absent).
+ * A genuinely absent sidecar is fine and stays silent, but a sidecar that
+ * exists yet cannot be copied (permissions/lock) is logged as a warning so an
+ * incomplete backup never passes unnoticed — a missing/locked sidecar must
+ * still never fail the backup itself.
+ */
+function copyIfExists(src, dest, logger) {
+  if (!existsSync(src)) return false;
+  try {
+    copyFileSync(src, dest);
+    return true;
+  } catch (err) {
+    logger?.warn?.(
+      `Read-model backup: could not copy ${src} (continuing): ${err?.message ?? err}`,
+    );
+  }
+  return false;
+}
+
+/**
+ * Snapshot every per-node read model before an upgrade swaps the gateway
+ * binary. For each `<dataDir>/node-*` that has a `read-model.sqlite`, copy it —
+ * plus its `-wal` sidecar (WAL mode keeps uncheckpointed pages there) and the
+ * `-shm` shared-memory index — to a timestamped file under a
+ * `read-model-backups/` subdir. We also grab the coherent point-in-time set
+ * (`snapshot.*.bin` + `journal.head`) when present, and prune to a bounded ring
+ * of prior backups. Best-effort: any failure is logged and swallowed so it can
+ * never block the upgrade itself.
+ *
+ * @param {string|null} oldVersion  version being replaced (used in the filename)
+ * @param {number} ring             prior backups to keep per node
+ * @returns {string[]} paths of the primary `.sqlite` copies written
+ */
+function backupReadModelsBeforeUpgrade(oldVersion, ring = READ_MODEL_BACKUP_RING) {
+  const logger = getLogger();
+  const dataDir = getDataDir();
+  const written = [];
+
+  let nodeDirs;
+  try {
+    nodeDirs = readdirSync(dataDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name.startsWith('node-'))
+      .map((d) => d.name);
+  } catch {
+    return written; // no data dir yet — nothing to back up
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  // Append a short random token so two backup runs landing in the same
+  // millisecond (parallel starts, or a retry loop) can't derive an identical
+  // stem and clobber each other's pre-upgrade set.
+  const uniq = randomBytes(3).toString('hex');
+  const verTag = sanitizeVersionTag(oldVersion);
+
+  for (const node of nodeDirs) {
+    const nodeDir = join(dataDir, node);
+    const readModel = join(nodeDir, 'read-model.sqlite');
+    if (!existsSync(readModel)) continue; // in-memory node, or never projected
+
+    const backupDir = join(nodeDir, 'read-model-backups');
+    const stem = `read-model.pre-upgrade-${verTag}-${ts}-${uniq}`;
+    try {
+      mkdirSync(backupDir, { recursive: true });
+
+      // Primary DB + its WAL/SHM sidecars (uncheckpointed pages live in -wal).
+      const destSqlite = join(backupDir, `${stem}.sqlite`);
+      copyFileSync(readModel, destSqlite);
+      written.push(destSqlite);
+      copyIfExists(join(nodeDir, 'read-model.sqlite-wal'), join(backupDir, `${stem}.sqlite-wal`), logger);
+      copyIfExists(join(nodeDir, 'read-model.sqlite-shm'), join(backupDir, `${stem}.sqlite-shm`), logger);
+
+      // Coherent point-in-time set: journal head + all snapshot bins.
+      copyIfExists(join(nodeDir, 'journal.head'), join(backupDir, `${stem}.journal.head`), logger);
+      for (const f of readdirSync(nodeDir)) {
+        if (/^snapshot\..*\.bin$/.test(f)) {
+          copyIfExists(join(nodeDir, f), join(backupDir, `${stem}.${f}`), logger);
+        }
+      }
+
+      logger.info(`Backed up read model before upgrade: ${destSqlite}`);
+      pruneReadModelBackups(backupDir, ring, logger);
+    } catch (err) {
+      logger.warn(
+        `Read-model backup for ${node} failed (continuing upgrade): ${err?.message ?? err}`,
+      );
+    }
+  }
+  return written;
+}
+
+/**
+ * Keep only the newest `ring` pre-upgrade backup sets in `backupDir`, deleting
+ * the oldest. A "set" is all files sharing a `read-model.pre-upgrade-*` stem
+ * (the `.sqlite` plus its `-wal`/`-shm`/`journal.head`/`snapshot.*` siblings),
+ * identified by the primary `.sqlite` file and ordered by its mtime.
+ */
+function pruneReadModelBackups(backupDir, ring = READ_MODEL_BACKUP_RING, logger = getLogger()) {
+  if (!(ring > 0)) return;
+  let entries;
+  try {
+    entries = readdirSync(backupDir);
+  } catch {
+    return;
+  }
+
+  const stems = entries
+    .filter((f) => f.startsWith('read-model.pre-upgrade-') && f.endsWith('.sqlite'))
+    .map((f) => f.slice(0, -'.sqlite'.length));
+  if (stems.length <= ring) return;
+
+  const withTime = stems.map((stem) => {
+    let mtime = 0;
+    try {
+      mtime = statSync(join(backupDir, `${stem}.sqlite`)).mtimeMs;
+    } catch {
+      /* fall back to 0 so an unreadable set sorts oldest and is dropped first */
+    }
+    return { stem, mtime };
+  });
+  withTime.sort((a, b) => a.mtime - b.mtime);
+
+  for (const { stem } of withTime.slice(0, withTime.length - ring)) {
+    for (const f of entries) {
+      if (f === `${stem}.sqlite` || f.startsWith(`${stem}.`)) {
+        try {
+          rmSync(join(backupDir, f), { force: true });
+        } catch {
+          /* best-effort prune */
+        }
+      }
+    }
+    logger.info(`Pruned old read-model backup set: ${join(backupDir, stem)}.*`);
+  }
+}
+
 /**
  * Resolve the ProcessOS binary to run, downloading it on demand when the user
  * has a PROCESSOS_DOWNLOAD_URL but no local copy yet. Resolution:
@@ -7335,6 +7684,19 @@ async function resolveProcessosBinary(req) {
       if (haveCached && remoteVer) {
         logger.info(`Updating ProcessOS ${haveVer ?? '?'} -> ${remoteVer} ...`);
       }
+      // Before swapping the binary for a different version, snapshot each
+      // node's read model so a schema-changing release can never silently
+      // destroy completed-instance history (issue #85). First download of a
+      // fresh install (no cached copy) is not an upgrade, so it is skipped.
+      if (haveCached) {
+        try {
+          backupReadModelsBeforeUpgrade(haveVer);
+        } catch (err) {
+          logger.warn(
+            `Pre-upgrade read-model backup failed (continuing upgrade): ${err?.message ?? err}`,
+          );
+        }
+      }
       await downloadProcessosBinary(processosBinaryUrl(dlUrl), cached);
       // Record what we fetched so the update notifier/status can compare later.
       try {
@@ -7973,6 +8335,12 @@ function parseProcessosRequest(args, flags) {
 // Internal helpers exported for tests/tooling only. c8ctl consumes just
 // `metadata` and `commands`; these named exports are inert to it.
 export { resolveBinary, findBinary, launcherEnvMarkers };
+export {
+  backupReadModelsBeforeUpgrade,
+  pruneReadModelBackups,
+  sanitizeVersionTag,
+  READ_MODEL_BACKUP_RING,
+};
 export { setConfig, unsetConfig, readConfig, writeConfig, getConfigFile, SETTING_ALIASES };
 export { buildNpmInvocation };
 export { resolveAgenticConfig, LOCAL_AGENTIC_TOKEN };
@@ -8069,6 +8437,9 @@ export {
   formatDuration,
   summarizeSupervisorWorker,
   formatSupervisorStatus,
+  reageSupervisorStatus,
+  clampToWidth,
+  createSupervisorLiveView,
   printSupervisorStatus,
   supervisorStatusSignature,
   supervisorJobCell,
@@ -8129,7 +8500,7 @@ export const metadata = {
         { command: 'c8ctl nano work coder --auto', description: 'Zero-config: serve every deployed agent job type read straight from the engine — no capability, no wiring (great for a local single-tenant plane)' },
         { command: 'c8ctl nano work coder --auto --auto-scope my-app', description: 'Zero-config, scoped to one app: serve only agent job types deployed under process ids prefixed "my-app"' },
         { 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: 'NANO_AGENTIC_URL=http://localhost:8080 NANO_AGENTIC_SECRET=<shared-secret> c8ctl nano work reviewer', description: 'Enrol the worker on the app\'s same-port /agentic channel in SECURE mode (same NANO_AGENTIC_SECRET as the server) 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.35.2",
+  "version": "1.35.4",
   "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.35.2",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.35.2",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.35.2",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.35.2",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.35.2",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.35.2",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.35.2"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.35.4",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.35.4",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.35.4",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.35.4",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.35.4",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.35.4",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.35.4"
   }
 }