c8ctl-plugin-nano 1.72.0 → 1.73.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +76 -12
  2. package/c8ctl-plugin.js +1115 -30
  3. package/package.json +8 -8
package/README.md CHANGED
@@ -1248,6 +1248,7 @@ c8ctl nano supervisor add reviewer --instances 3 # add 3 distinct auto-named
1248
1248
  c8ctl nano supervisor restart reviewer # by worker id or profile name
1249
1249
  c8ctl nano supervisor reload # adopt new code fleet-wide (rolling drain+respawn, zero downtime)
1250
1250
  c8ctl nano supervisor reload reviewer # reload just one worker/profile
1251
+ c8ctl nano supervisor upgrade # roll the DAEMON itself onto the on-disk code (adopts the running workers — no drain, no killed jobs)
1251
1252
  c8ctl nano supervisor reload-credentials # after `gh auth login`/refresh: every worker re-reads its gh token now (async; old token served until the re-read lands; no drain)
1252
1253
  c8ctl nano supervisor remove coder # stop + drop a worker (also: `all`)
1253
1254
  c8ctl nano supervisor logs reviewer --follow # tail a worker's log (or the daemon's)
@@ -1355,18 +1356,81 @@ c8ctl nano supervisor reload # roll it into the running fleet, zero downtime
1355
1356
  new code there.
1356
1357
  - **Scope — workers, not the daemon.** A reload adopts all **worker-side** code
1357
1358
  (job running, agent instances, git/container provisioning, the agentic
1358
- connection, the Effect runtime workers load — the bulk of the harness). The
1359
- supervisor **daemon** keeps running the code it started with: its workers are
1360
- its children and watch its pid, so re-exec'ing the daemon would take the fleet
1361
- down with it. To adopt new **supervisor** code, do a full restart
1362
- (`c8ctl nano supervisor stop && c8ctl nano supervisor start`) — a rare event,
1363
- since the daemon is a thin process manager. `supervisor status` shows an
1364
- `on disk:` line flagging "update available" whenever the code on disk has
1365
- advanced past the running daemon, so you know when a reload (or restart) is
1366
- worthwhile. While a reload is in progress, `supervisor status` also prints a
1367
- `reload:` line (`rolling N/M adopted — draining <id> — do not restart the
1368
- daemon`) so a detached operator can see the roll without staying attached to
1369
- the streaming `reload` command.
1359
+ connection, the Effect runtime workers load — the bulk of the harness). To adopt
1360
+ new **supervisor** (daemon) code, use `supervisor upgrade` (below) — no fleet
1361
+ outage, no killed jobs. `supervisor status` shows an `on disk:` line flagging
1362
+ "update available" whenever the code on disk has advanced past the running
1363
+ daemon, so you know when a reload (or upgrade) is worthwhile. While a reload
1364
+ is in progress, `supervisor status` also prints a `reload:` line (`rolling N/M
1365
+ adopted — draining <id> — do not restart the daemon`) so a detached operator
1366
+ can see the roll without staying attached to the streaming `reload` command.
1367
+
1368
+ ### Rolling daemon hot-upgrade: `supervisor upgrade`
1369
+
1370
+ `supervisor reload` rolls the **workers**; `supervisor upgrade` (alias
1371
+ `supervisor reload --daemon`) rolls the **daemon itself** onto the on-disk code —
1372
+ again with **zero fleet downtime and no killed in-flight jobs**. Instead of
1373
+ draining anything, it swaps the parent process out from under the running
1374
+ workers:
1375
+
1376
+ ```bash
1377
+ c8ctl nano update # pull the new plugin onto disk
1378
+ c8ctl nano supervisor upgrade # the daemon hands the fleet to a successor on the new code
1379
+ ```
1380
+
1381
+ 1. A **successor** daemon (the new code) starts and asks the old daemon to
1382
+ **quiesce** — it stops accepting new control connections and refuses further
1383
+ mutations, but **keeps the workers running**.
1384
+ 2. The successor **takes the control socket** and **adopts the old daemon's
1385
+ workers** from the persisted state — each is tracked by its existing pid and
1386
+ polled for liveness (a crash still restarts it with the usual backoff). The
1387
+ workers are **never signaled** at this point, so in-flight jobs run
1388
+ undisturbed.
1389
+ 3. The successor then **retargets each worker's parent-death watchdog** to
1390
+ itself (a `SIGUSR2` the worker reads as "upgrade, keep serving" — not a drain
1391
+ — because the successor's pid rides the worker's `<activity>.upgrade`
1392
+ sidecar), waits for the workers to acknowledge, and only then releases the
1393
+ old daemon, which persists a final snapshot and **exits without touching the
1394
+ workers**.
1395
+
1396
+ Workers never die mid-job — only the parent process is swapped. While the roll
1397
+ is in flight `supervisor status` shows it
1398
+ (`upgrade: rolling <old-version> → <new-version>`), the same visibility the
1399
+ worker roll has. **Ctrl-C detaches** the client — the swap completes in the
1400
+ background. A successor that can't reach a quiesced old daemon exits and leaves
1401
+ the fleet untouched, so a failed upgrade never strands the workers.
1402
+
1403
+ - **Not supported on Windows** (the watchdog retarget relies on `SIGUSR2`,
1404
+ which Windows cannot deliver) — use `supervisor stop` + `start` there, as
1405
+ before.
1406
+ - **Installed services (`supervisor install`).** The upgrade spawns the
1407
+ successor as a **detached process in the invoking session**, not under
1408
+ launchd/systemd. Two consequences follow. First, the successor is no longer
1409
+ service-supervised: on macOS-over-SSH it loses the logout protection the
1410
+ LaunchAgent provided, and under systemd the old unit's clean (exit 0) handover
1411
+ does NOT trigger a service restart (the generated units use crash-only
1412
+ policies — `Restart=on-failure` / `KeepAlive={SuccessfulExit:false}` — so a
1413
+ successful exit correctly stays down). Second, the service's supervision of
1414
+ the fleet is suspended until you re-establish it. **After upgrading a
1415
+ service-managed daemon, re-run `c8ctl nano supervisor install`** (or
1416
+ `stop` + `start`) to bring the new-code daemon back under the service. A
1417
+ fully service-owned handoff (systemd `NOTIFY` / socket activation) is a
1418
+ possible future increment; today the upgrade is a session-level operation.
1419
+ - **Worker log piping across the swap.** With log capping on (the default),
1420
+ each worker's stdout/stderr is piped through the daemon that spawned it. A
1421
+ daemon upgrade adopts a worker by pid but cannot inherit that pipe, so output
1422
+ a long-lived worker emits *after* the old daemon exits is not captured by the
1423
+ new daemon's log ring (and a worker writing to a fully-drained pipe could see
1424
+ `EPIPE`). Workers spawned or restarted *after* the upgrade are piped through
1425
+ the new daemon normally. If you need uninterrupted logs across a daemon
1426
+ upgrade, run with `NANO_SUPERVISOR_LOG_MAX_BYTES=0` (workers append directly
1427
+ to their log file, which survives the swap) or roll the workers afterward
1428
+ with `supervisor reload`.
1429
+ - Tunables (rarely needed): `NANO_SUPERVISOR_UPGRADE_QUIESCE_TIMEOUT_MS` (how
1430
+ long the successor waits for the old daemon to quiesce, default 30s),
1431
+ `NANO_SUPERVISOR_UPGRADE_ACK_TIMEOUT_MS` (how long the handoff waits for the
1432
+ workers' watchdog-retarget acks, default 15s), `NANO_SUPERVISOR_ADOPT_POLL_MS`
1433
+ (how often an adopted worker's pid is polled for liveness, default 2s).
1370
1434
 
1371
1435
  ### Surviving SSH logout: `supervisor install` / `uninstall`
1372
1436