c8ctl-plugin-nano 1.18.1 → 1.20.0

package/README.md

@@ -24,7 +24,7 @@ It adds a single `nano` command:
 
 ```bash
 c8ctl nano start|status|stop|restart|logs|pause|resume|clean|set|config|update
-c8ctl nano hire|work   # turn a CLI agent harness into a Nano job worker
+c8ctl nano hire|assign|work   # hire/assign manage agent profiles; work runs one as a Nano job worker
 ```
 
 `nano start N` spawns **N** nanobpmn node processes wired to talk to each other
@@ -157,6 +157,24 @@ c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all
 c8ctl nano hire --list
 ```
 
+**`assign <name> [capabilities...]`** grants new capabilities (roles) to an
+existing hire without re-running `hire`. Capabilities are **added** to (unioned
+with) the profile's current set — `assign` never removes a role — and the
+updated job-type matrix is printed. Restart the profile's workers so they pick
+up the new job types:
+
+```bash
+# Give an existing reviewer two more capabilities
+c8ctl nano assign reviewer triage refactoring
+
+# --capabilities works too (comma-separated), equivalent to the positionals above
+c8ctl nano assign reviewer --capabilities triage,refactoring
+
+# then restart its workers to service the new job types
+c8ctl nano work reviewer
+```
+
+
 **`work <name>`** loads the profile, connects with the c8ctl SDK client, and
 registers one job worker per token in the **rank × capability matrix**, then
 polls for work in the foreground until Ctrl-C. For rank `senior` and
@@ -189,6 +207,29 @@ c8ctl nano work reviewer                     # poll for work until Ctrl-C
 c8ctl nano work reviewer --max-parallel 2 --job-timeout 600000
 ```
 
+### Live profile reload (no restart on `assign`)
+
+A running `c8ctl nano work <name>` **watches** the profile it is servicing. When
+you extend or reduce that profile's capabilities in another terminal —
+
+```bash
+c8ctl nano assign reviewer fix-ci     # add a capability to the live profile
+```
+
+— the supervisor reconciles its pollers in place: it **starts** pollers for the
+newly added rank×capability job types and **gracefully drains** the pollers for
+removed types — best-effort: each draining poller is given a bounded grace
+window (`STOP_GRACE_MS`) for its in-flight jobs to finish before
+it is stopped, so long-running work exceeding that window may still be
+interrupted. Unchanged job types keep running undisturbed, so there is no need
+to stop and restart the worker.
+
+Only **job types** (rank + capabilities, plus any `--job-type` extras) reconcile
+live. Changes to the profile's `command`, `model`, `sandbox`/`image`, or `env`
+still require a restart to take effect. If the profile is deleted or the config
+file is mid-write when the reload fires, the running workers are **kept** (never
+torn down) and a warning is logged.
+
 Each activated job runs the profile's command **once** (one-shot): the job is
 serialized to JSON and piped to the CLI's **stdin** —
 
@@ -217,6 +258,16 @@ config`).
 > Raising `--job-timeout` alone does **not** fix this — it moves both coupled
 > deadlines together; widen `--lock-grace` (or keep the default) instead.
 
+> **Long-poll window.** `--poll-timeout` (default `30000`ms) is how long the
+> broker holds each `activateJobs` request open waiting for work before returning
+> empty. A longer window keeps an idle worker on **one** connection for that whole
+> window instead of reconnecting every few seconds — cutting the number of
+> connection establishments, and thus the chances of hitting a transient connect
+> error (`ECONNREFUSED` / connect-timeout) on a flaky link. It maps straight to
+> the SDK's `pollTimeoutMs` → the broker's `requestTimeout`: `0` selects the
+> broker's own default (~5s) and a negative value returns immediately when no job
+> is available.
+
 > **Trust boundary.** The profile `command` is run through a shell so you can
 > write a full invocation (args, pipes, multi-word commands). It is
 > **operator-authored** — only what you put in your own `config.json` is
@@ -246,6 +297,16 @@ Element templates emit flat dotpath header keys (strings); the plugin expands
 them into a nested object and coerces `"true"/"false"` → bool and numeric
 strings → int. The normalized shape is
 `{ schemaVersion, repository{provider,url,ref,depth,submodules,authRef}, branch{base,create,push}, setup{commands,env,secretRefs}, task{prompt,promptFile,maxIterations,timeoutMs,allowPr,prBase} }`.
+
+**Prompt = base + optional verbatim append.** The agent's prompt resolves to
+`task.prompt` (typically a model header filled at deploy time), falling back to a
+plain `prompt`/`task` variable. Because a header-delivered base prompt can't be
+composed in FEEL, a task may supply per-instance context via **`task.appendPrompt`**
+(reserved) or a plain **`appendPrompt`** variable — it is concatenated onto the base
+**verbatim, with no injected separator** (the model's ioMapping owns any leading
+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.
 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
 provisioned (below) it also carries `{repository, branch, baseSha, headSha, commits[], pushed, pushError?, gitError?, pr?}`.

package/c8ctl-plugin.js

@@ -43,6 +43,8 @@ import {
   statfsSync,
   lstatSync,
   mkdtempSync,
+  watchFile,
+  unwatchFile,
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { homedir, platform as osPlatform, devNull } from 'node:os';
@@ -200,20 +202,39 @@ function getConfigFile() {
   return join(getStateHome(), CONFIG_FILE);
 }
 
-function readConfig() {
+function readConfigStrict() {
   const file = getConfigFile();
   if (!existsSync(file)) return {};
+  const cfg = JSON.parse(readFileSync(file, 'utf-8'));
+  return cfg && typeof cfg === 'object' ? cfg : {};
+}
+
+function readConfig() {
   try {
-    const cfg = JSON.parse(readFileSync(file, 'utf-8'));
-    return cfg && typeof cfg === 'object' ? cfg : {};
+    return readConfigStrict();
   } catch {
+    // A malformed/torn config.json is swallowed here so ordinary callers get an
+    // empty map; callers that must tell "absent" from "unreadable" apart use
+    // readConfigStrict() directly and handle the throw.
     return {};
   }
 }
 
 function writeConfig(cfg) {
   mkdirSync(getStateHome(), { recursive: true });
-  writeFileSync(getConfigFile(), JSON.stringify(cfg, null, 2));
+  // Atomic write: serialize to a temp file in the same dir, then rename over the
+  // target. A rename is atomic on a POSIX filesystem, so a concurrent reader
+  // (e.g. `work`'s profile watcher, or another `assign`) never observes a
+  // half-written config.json and JSON.parse never sees a torn file.
+  const target = getConfigFile();
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+  try {
+    renameSync(tmp, target);
+  } catch (err) {
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    throw err;
+  }
 }
 
 /**
@@ -368,7 +389,7 @@ function launcherEnvMarkers(resolved) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'work'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'assign', 'work'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -1518,7 +1539,32 @@ function deriveJobLockMs(jobTimeoutMs, lockGraceMs) {
   return { killMs, lockMs: killMs + grace };
 }
 
-/** A profile name must be a safe, filesystem/token-friendly slug. */
+/**
+ * Resolve the broker long-poll window (ms) each `activateJobs` request is held
+ * open before returning empty. A longer window keeps an idle worker on ONE open
+ * connection for that whole window instead of reconnecting every few seconds,
+ * cutting the number of connection establishments — and thus the number of
+ * chances to hit a transient connect failure (ECONNREFUSED / connect-timeout)
+ * on a flaky link.
+ *
+ * The value is passed straight through to the SDK as `pollTimeoutMs` → the
+ * broker's `requestTimeout`, so the documented broker semantics apply: `0` =
+ * broker default (~5s), a negative value = return immediately when no job is
+ * available. Parsing is `parseInt`-style: only a flag with no leading integer
+ * (absent, blank, or non-numeric such as `"abc"`) falls back to the default,
+ * while a leading integer with trailing junk (e.g. `"30000ms"`) is honoured as
+ * that integer. `0` and negatives are honoured too (which is why this cannot
+ * reuse `intFlag`, whose "> 0" guard would floor them to the default).
+ *
+ * @returns {number}
+ */
+function derivePollTimeoutMs(flagValue, dflt = 30_000) {
+  if (flagValue === undefined || flagValue === null || String(flagValue).trim() === '') {
+    return dflt;
+  }
+  const n = Number.parseInt(String(flagValue), 10);
+  return Number.isFinite(n) ? n : dflt;
+}
 function isValidProfileName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name);
 }
@@ -1540,6 +1586,21 @@ function jobTypeMatrix(rank, capabilities) {
   return [...new Set(tokens)];
 }
 
+/**
+ * Diff a running set of job-type pollers against a desired set. Pure so the
+ * profile-watch reconcile in `work` (which starts pollers for `added` types and
+ * gracefully drains pollers for `removed` types) is unit-testable. Order in the
+ * returned arrays is stable (desired order for `added`, current order for
+ * `removed`) for deterministic logging.
+ */
+function diffJobTypes(current, desired) {
+  const cur = new Set(current);
+  const want = new Set(desired);
+  const added = [...want].filter((t) => !cur.has(t));
+  const removed = [...cur].filter((t) => !want.has(t));
+  return { added, removed };
+}
+
 /** All persisted hire profiles, keyed by name. */
 function readHires() {
   const cfg = readConfig();
@@ -1548,6 +1609,16 @@ function readHires() {
   return cfg.hires && typeof cfg.hires === 'object' && !Array.isArray(cfg.hires) ? cfg.hires : {};
 }
 
+/**
+ * Like readHires(), but propagates a malformed-config parse error instead of
+ * swallowing it. Lets a caller distinguish "profile genuinely removed" from
+ * "config temporarily unreadable/torn" so it can report an accurate reason.
+ */
+function readHiresStrict() {
+  const cfg = readConfigStrict();
+  return cfg.hires && typeof cfg.hires === 'object' && !Array.isArray(cfg.hires) ? cfg.hires : {};
+}
+
 /** Persist a single hire profile into config.json under `hires`. */
 function writeHire(profile) {
   const cfg = readConfig();
@@ -1597,7 +1668,99 @@ function normalizeStoredProfile(name, profile) {
 }
 
 /**
- * hire — create (or overwrite) an agent profile. Interactive by default; every
+ * Merge additional capabilities into an already-normalized profile, returning a
+ * new profile object with the union of capabilities (canonical order) and a
+ * refreshed `updatedAt`. Pure (no config I/O), so it is unit-testable. Existing
+ * fields — including `createdAt` — are preserved. `incoming` may be a
+ * comma-string or an array. Returns `{ profile, added }`, where `added` lists
+ * the newly gained capabilities (empty when the assign is a no-op).
+ */
+function applyAssign(existing, incoming, now = new Date().toISOString()) {
+  const before = new Set(normalizeCapabilities(existing && existing.capabilities));
+  const union = normalizeCapabilities([...before, ...normalizeCapabilities(incoming)]);
+  const added = union.filter((c) => !before.has(c));
+  return {
+    profile: { ...existing, capabilities: union, updatedAt: now },
+    added,
+  };
+}
+
+/**
+ * Resolve the profile name and the raw comma-joined capability string for an
+ * `assign` invocation from parsed positionals + flags. Pure (no I/O) so the
+ * positional-slicing rules are unit-testable.
+ *
+ * When `--name` is supplied the name does NOT consume a positional, so every
+ * positional is a capability. Otherwise the first positional is the name and
+ * the rest are capabilities. `--capabilities a,b` is always appended.
+ */
+function resolveAssignInputs(req, flags) {
+  const positional = Array.isArray(req?.positional) ? req.positional : [];
+  const name = flags?.name ? String(flags.name).trim() : positional[0];
+  const positionalCaps = flags?.name ? positional : positional.slice(1);
+  const flagCaps = flags?.capabilities !== undefined ? String(flags.capabilities) : '';
+  const incomingRaw = [...positionalCaps, flagCaps].filter(Boolean).join(',');
+  return { name, incomingRaw };
+}
+
+/**
+ * assign — grant new capabilities (roles) to an existing hire without
+ * re-running `hire`. The profile name is positional[0] (or `--name`);
+ * capabilities are the remaining positionals and/or `--capabilities a,b`.
+ * Capabilities are unioned with the profile's existing set (additive; assign
+ * never removes a role) and the updated rank×capability job-type matrix is
+ * printed. Re-run `work` to pick up the new job types.
+ */
+async function assignCapabilities(req, flags) {
+  const logger = getLogger();
+  const { name, incomingRaw } = resolveAssignInputs(req, flags);
+  if (!name) {
+    logger.error('Usage: c8ctl nano assign <profileName> [<capability> ...] [--name <n>] [--capabilities <a,b>]');
+    logger.info('Grant new capabilities to an existing hire. List profiles with: c8ctl nano hire --list');
+    process.exit(1);
+  }
+  if (!isValidProfileName(name)) {
+    logger.error(`Invalid profile name "${name}". Use letters, digits, dot, dash or underscore.`);
+    process.exit(1);
+  }
+
+  if (normalizeCapabilities(incomingRaw).length === 0) {
+    logger.error('Provide at least one capability to assign.');
+    logger.info(`Example: c8ctl nano assign ${name} code-review testing`);
+    process.exit(1);
+  }
+
+  const raw = readHires()[name];
+  if (!raw) {
+    logger.error(`No hire named "${name}". List profiles with: c8ctl nano hire --list`);
+    process.exit(1);
+  }
+  const normalized = normalizeStoredProfile(name, raw);
+  if (normalized.error) {
+    logger.error(`Cannot assign to "${name}": ${normalized.error}. Re-create it with: c8ctl nano hire`);
+    process.exit(1);
+  }
+
+  // Preserve createdAt (normalizeStoredProfile drops it) on the canonical form.
+  const base = {
+    ...normalized.profile,
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : new Date().toISOString(),
+  };
+  const { profile, added } = applyAssign(base, incomingRaw);
+  if (added.length === 0) {
+    logger.info(`"${name}" already has: ${profile.capabilities.join(', ') || '(none)'} — no change.`);
+    return;
+  }
+  writeHire(profile);
+
+  const matrix = jobTypeMatrix(profile.rank, profile.capabilities);
+  logger.info(`Assigned to "${name}" [${profile.rank}]: +${added.join(', ')}`);
+  logger.info(`  capabilities: ${profile.capabilities.join(', ')}`);
+  logger.info(`  job types (${matrix.length}): ${matrix.join('  ')}`);
+  logger.info(`Restart its workers to pick up the new roles: c8ctl nano work ${name}`);
+}
+
+/**
  * field can also be supplied via a flag (--name/--rank/--command/--model/
  * --capabilities) for scripting. Prompts only for the fields still missing.
  * `--list` prints existing profiles instead.
@@ -2006,8 +2169,21 @@ 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);
+  // 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
+  // base with NO injected separator — the caller (the model's ioMapping) owns any leading
+  // separator/preamble — so a null/empty append leaves the base prompt untouched.
+  const appendPrompt = str(task.appendPrompt) ?? str(variables?.appendPrompt);
+  const prompt =
+    appendPrompt != null && appendPrompt !== ''
+      ? `${basePrompt ?? ''}${appendPrompt}`
+      : basePrompt;
   env.task = {
-    prompt: str(task.prompt) ?? str(variables?.prompt) ?? str(variables?.task),
+    prompt,
     promptFile: str(task.promptFile),
     maxIterations: coerceInt(task.maxIterations, undefined),
     timeoutMs: coerceInt(task.timeoutMs, undefined),
@@ -2730,6 +2906,11 @@ async function workAgent(req, flags) {
   // MUST enforce the clamped `jobKillMs` (not the raw --job-timeout), or a very
   // large --job-timeout would outlive the broker lock and re-break the invariant.
   const { killMs: jobKillMs, lockMs: jobLockMs } = deriveJobLockMs(jobTimeoutMs, lockGraceMs);
+  // Broker long-poll window: how long each activateJobs request is held open
+  // waiting for work. 30s default so idle workers hold one connection open ~30s
+  // rather than reconnecting every few seconds — fewer reconnects, fewer chances
+  // to hit a transient connect error on a flaky link. Passed to the SDK verbatim.
+  const pollTimeoutMs = derivePollTimeoutMs(flags?.['poll-timeout']);
 
   // Sandbox: flag overrides the stored profile default. `none` runs on the host
   // (legacy); `docker`/`podman` run each job in a throwaway labelled container.
@@ -2837,15 +3018,19 @@ async function workAgent(req, flags) {
   if (profileEnvKeys.length > 0) logger.info(`  harness env: ${profileEnvKeys.join(', ')}`);
   const extraNote = extraJobTypes.length > 0 ? ` (${extraJobTypes.length} via --job-type)` : '';
   logger.info(`  listening on ${jobTypes.length} job type(s)${extraNote}: ${jobTypes.join('  ')}`);
-  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobKillMs}ms; activation lock: ${jobLockMs}ms`);
+  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobKillMs}ms; activation lock: ${jobLockMs}ms; poll timeout: ${pollTimeoutMs}ms`);
   logger.info('Polling for work — press Ctrl-C to stop.');
 
-  const workers = jobTypes.map((jobType) =>
+  // A per-job-type worker factory. Captures all the CLI-local + profile context
+  // in closure scope so the profile watcher below can (re)spawn a poller for any
+  // job type on demand without re-reading the flags.
+  const makeWorker = (jobType) =>
     camunda.createJobWorker({
       jobType,
       workerName: `${name}:${jobType}`,
       maxParallelJobs,
       jobTimeoutMs: jobLockMs,
+      pollTimeoutMs,
       jobHandler: async (job) => {
         logger.info(`[${jobType}] job ${job.jobKey} (instance ${job.processInstanceKey ?? '-'}) → ${buildAgentCommandLine(profile.command, effectiveArgs)}`);
 
@@ -3020,35 +3205,172 @@ async function workAgent(req, flags) {
           variables: { [AGENT_RESULT_KEY]: resultEnvelope },
         });
       },
-    }),
-  );
+    });
+
+  // Live worker registry keyed by job type, so the profile watcher can add or
+  // drain individual pollers without disturbing the others. `draining` is the
+  // shutdown latch (shared with the watcher so a reconcile can't race a stop).
+  const workers = new Map();
+  let draining = false;
+
+  const drainWorker = async (w) => {
+    try {
+      if (typeof w.stopGracefully === 'function') {
+        await w.stopGracefully({ waitUpToMs: STOP_GRACE_MS });
+      } else if (typeof w.stop === 'function') {
+        await w.stop();
+      }
+      return true;
+    } catch {
+      return false; // best-effort: never let one worker's stop failure hang us
+    }
+  };
+
+  const spawnJobType = (jobType) => {
+    if (workers.has(jobType)) return false;
+    workers.set(jobType, makeWorker(jobType));
+    return true;
+  };
+
+  for (const jobType of jobTypes) spawnJobType(jobType);
+
+  // ---- Live profile watch: reconcile the poller set when the watched profile's
+  // job types change (e.g. `c8ctl nano assign <name> …`) — start pollers for
+  // added types, gracefully drain pollers for removed types — without a restart
+  // and without disturbing unchanged types' in-flight work. ----
+  const configFile = getConfigFile();
+  const WATCH_INTERVAL_MS = 1500;
+  let reconciling = false;
+  // Set when a profile change arrives while a reconcile is already in flight, so
+  // we run one more pass after the current drain completes instead of dropping
+  // the update until the next change fires.
+  let reconcileRequested = false;
+  // Handle to the in-flight reconcile so shutdown can wait for it to finish
+  // before snapshotting `workers` (avoids double-stops / missed drains).
+  let inFlightReconcile = null;
+
+  // Desired job types from the CURRENT on-disk profile (matrix ∪ --job-type
+  // extras). Returns { skip } for a transient/torn read, a vanished profile, or
+  // an invalid edit — callers must then KEEP the running set, never tear down.
+  const desiredJobTypes = () => {
+    let stored;
+    try {
+      stored = readHiresStrict()[name];
+    } catch {
+      // config.json exists but doesn't parse (e.g. a torn write): the profile is
+      // NOT necessarily gone, so don't claim it was deleted — skip this pass.
+      return { skip: 'config unreadable' };
+    }
+    if (!stored) return { skip: 'deleted' };
+    const norm = normalizeStoredProfile(name, stored);
+    if (norm.error) return { skip: norm.error };
+    const m = jobTypeMatrix(norm.profile.rank, norm.profile.capabilities);
+    return { jobTypes: [...new Set([...m, ...extraJobTypes])] };
+  };
+
+  const reconcile = () => {
+    if (draining) return inFlightReconcile || Promise.resolve();
+    if (reconciling) {
+      // A change landed mid-reconcile — remember it so the current pass loops
+      // once more rather than leaving the worker set stale until the next edit.
+      // Return the ACTUAL in-flight promise (not a fresh short-lived one) so a
+      // caller — including shutdown — waits for the real reconcile to finish.
+      reconcileRequested = true;
+      return inFlightReconcile || Promise.resolve();
+    }
+    reconciling = true;
+    reconcileRequested = false;
+    inFlightReconcile = (async () => {
+      try {
+        do {
+          reconcileRequested = false;
+          await runReconcilePass();
+        } while (reconcileRequested && !draining);
+      } finally {
+        reconciling = false;
+        inFlightReconcile = null;
+      }
+    })();
+    return inFlightReconcile;
+  };
+
+  const runReconcilePass = async () => {
+      const desired = desiredJobTypes();
+      if (desired.skip) {
+        if (desired.skip === 'deleted') {
+          logger.warn(`Profile "${name}" is gone from config — keeping the current ${workers.size} worker(s) running.`);
+        } else {
+          logger.warn(`Profile "${name}" reload skipped — ${desired.skip}; keeping current workers.`);
+        }
+        return;
+      }
+      const { added, removed } = diffJobTypes([...workers.keys()], desired.jobTypes);
+      if (added.length === 0 && removed.length === 0) return;
+      logger.info(`Profile "${name}" changed — reconciling job types (+${added.length} / -${removed.length}).`);
+      for (const jt of added) {
+        spawnJobType(jt);
+        logger.info(`  + now listening on ${jt}`);
+      }
+      await Promise.all(
+        removed.map(async (jt) => {
+          const w = workers.get(jt);
+          logger.info(`  - draining ${jt} …`);
+          const ok = await drainWorker(w);
+          if (ok) {
+            // Only drop it from the registry once it has actually stopped, so a
+            // failed drain stays tracked and gets retried on the next reconcile
+            // pass (or on shutdown) instead of leaking an untracked poller.
+            workers.delete(jt);
+            logger.info(`  - stopped ${jt}`);
+          } else {
+            logger.warn(`  - ${jt} did not stop cleanly; keeping it tracked so it is retried on the next reconcile or shutdown.`);
+          }
+        }),
+      );
+      logger.info(`  now listening on ${workers.size} job type(s): ${[...workers.keys()].join('  ')}`);
+  };
+
+  // `watchFile` (polling stat) is deliberate over `fs.watch`: it survives the
+  // atomic temp+rename that `writeConfig` does (fs.watch would rebind to the old
+  // inode and go silent), and it's uniform across platforms. Profile edits are
+  // rare + manual, so a ~1.5s poll latency is fine.
+  watchFile(configFile, { interval: WATCH_INTERVAL_MS }, (curr, prev) => {
+    // Fires each interval; act only on real changes. Compare mtime, ctime and
+    // size, not mtime alone: on filesystems with coarse mtime resolution (or two
+    // edits within one mtime tick) mtimeMs can be unchanged while size/ctimeMs
+    // differ, and an mtime-only guard would skip a genuine profile update.
+    if (
+      curr.mtimeMs === prev.mtimeMs &&
+      curr.ctimeMs === prev.ctimeMs &&
+      curr.size === prev.size
+    ) return;
+    // `reconcile()` owns the `inFlightReconcile` handle: a change arriving while
+    // a reconcile is already running coalesces into the current pass and returns
+    // that same in-flight promise, so shutdown always waits for the real one.
+    reconcile().catch((err) => logger.warn(`profile reload failed: ${err?.message || err}`));
+  });
 
   // Keep the process alive until a stop signal, then drain gracefully.
   await new Promise((resolve) => {
-    let stopping = false;
     const stop = async (signal) => {
-      if (stopping) return;
-      stopping = true;
-      logger.info(`Received ${signal} — stopping ${workers.length} worker(s)...`);
+      if (draining) return;
+      draining = true;
+      // Stop watching first so no new reconcile can be triggered, then wait for
+      // any in-flight reconcile to finish before snapshotting `workers` — this
+      // prevents double-stops, missed drains, or a wrong worker count on exit.
+      unwatchFile(configFile);
+      if (inFlightReconcile) {
+        logger.info('Waiting for in-flight profile reconcile to finish before shutdown…');
+        await inFlightReconcile;
+      }
+      const list = [...workers.values()];
+      logger.info(`Received ${signal} — stopping ${list.length} worker(s)...`);
       if (reaperTimer) clearInterval(reaperTimer);
       if (runDirTimer) clearInterval(runDirTimer);
-      let stopFailures = 0;
-      await Promise.all(
-        workers.map(async (w) => {
-          try {
-            if (typeof w.stopGracefully === 'function') {
-              await w.stopGracefully({ waitUpToMs: STOP_GRACE_MS });
-            } else if (typeof w.stop === 'function') {
-              await w.stop();
-            }
-          } catch {
-            // best-effort: never let one worker's stop failure hang shutdown
-            stopFailures += 1;
-          }
-        }),
-      );
+      const results = await Promise.all(list.map(drainWorker));
+      const stopFailures = results.filter((ok) => !ok).length;
       if (stopFailures > 0) {
-        logger.warn(`${stopFailures} of ${workers.length} worker(s) did not stop cleanly; some connections may still be open.`);
+        logger.warn(`${stopFailures} of ${list.length} worker(s) did not stop cleanly; some connections may still be open.`);
       } else {
         logger.info('All workers stopped.');
       }
@@ -4373,6 +4695,7 @@ export {
   webConsoleUrl,
   consoleLinkLabel,
   hireWorker,
+  assignCapabilities,
 };
 export {
   normalizeTaskEnvelope,
@@ -4407,9 +4730,13 @@ export {
   agentRunsRoot,
   ProvisionError,
   normalizeStoredProfile,
+  applyAssign,
+  resolveAssignInputs,
   jobTypeMatrix,
+  diffJobTypes,
   parseJobTypeFlags,
   deriveJobLockMs,
+  derivePollTimeoutMs,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
   RESULT_SENTINEL,
@@ -4495,12 +4822,12 @@ export const commands = {
       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' },
       binary: { type: 'string', description: 'Path to the nanobpmn server binary' },
-      name: { type: 'string', description: 'hire/work: agent profile name (alt to positional arg)' },
+      name: { type: 'string', description: 'hire/work/assign: agent profile name (alt to positional arg)' },
       rank: { type: 'string', description: 'hire: agent rank (principal|senior|junior|decider)' },
       command: { type: 'string', description: 'hire: CLI command that runs the agent harness (e.g. copilot, claude, pi)' },
       arg: { type: 'string', multiple: true, description: 'hire/work: command-line switch/arg appended to the harness command (repeatable), e.g. --arg --allow-all. Persisted on hire; work appends more.' },
       model: { type: 'string', description: 'hire: model name passed to the harness (AGENT_MODEL)' },
-      capabilities: { type: 'string', description: 'hire: comma-separated capability list' },
+      capabilities: { type: 'string', description: 'hire/assign: comma-separated capability list' },
       sandbox: { type: 'string', description: 'hire/work: execution sandbox none|docker|podman (default none). Containers isolate each job.' },
       image: { type: 'string', description: 'hire/work: container image the agent runs in (required for --sandbox docker|podman)' },
       env: { type: 'string', multiple: true, description: 'hire/work: static env var for the harness as NAME=VALUE (repeatable); persisted on hire, work extends/overrides. E.g. permission toggles.' },
@@ -4515,6 +4842,7 @@ export const commands = {
       'max-parallel': { type: 'string', description: 'work: max concurrent jobs per worker (default 1)' },
       'job-timeout': { type: 'string', description: 'work: max harness runtime per job in ms; the spawned process is killed past this (default 300000)' },
       'lock-grace': { type: 'string', description: 'work: extra ms added to --job-timeout to derive the broker activation lock, so the worker reports before the lock lapses (default 120000)' },
+      'poll-timeout': { type: 'string', description: 'work: broker long-poll window in ms each activateJobs request is held open (fewer reconnects → fewer transient connect errors); default 30000, 0 = broker default, negative = return immediately' },
       'job-type': { type: 'string', multiple: true, description: 'work: extra job type to service alongside the rank×capability matrix (repeatable)' },
     },
     handler: async (args, flags) => {
@@ -4567,6 +4895,9 @@ export const commands = {
           case 'hire':
             await hireWorker(req, flags);
             break;
+          case 'assign':
+            await assignCapabilities(req, flags);
+            break;
           case 'work':
             await workAgent(req, flags);
             break;
@@ -4659,7 +4990,8 @@ function printUsage() {
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
   console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
-  console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-timeout <ms>] [--lock-grace <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
+  console.log('  c8ctl nano assign <profileName> [<capability> ...] [--name <n>] [--capabilities <a,b>]');
+  console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-timeout <ms>] [--lock-grace <ms>] [--poll-timeout <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -4674,6 +5006,7 @@ function printUsage() {
   console.log('  config   Show current configuration and on-disk locations');
   console.log('  update   Pull the latest published nano release (--check to only report)');
   console.log('  hire     Create a CLI agent worker profile (rank + capabilities → job-type matrix)');
+  console.log('  assign   Grant new capabilities (roles) to an existing hire (additive)');
   console.log('  work     Run a hired profile as Nano job workers, polling for work until Ctrl-C');
   console.log('');
   console.log('Options:');
@@ -4690,11 +5023,11 @@ function printUsage() {
   console.log('  --purge              stop: also delete per-node engine data');
   console.log('  --force              start: stop any existing cluster first');
   console.log('  --workspace          clean: also delete the workspace (models + workers)');
-  console.log('  --name <n>           hire/work: agent profile name (alt to positional arg)');
+  console.log('  --name <n>           hire/work/assign: agent profile name (alt to positional arg)');
   console.log('  --rank <r>           hire: agent rank (principal|senior|junior|decider)');
   console.log('  --command <c>        hire: CLI command that runs the agent harness');
   console.log('  --model <m>          hire: model name passed to the harness (AGENT_MODEL)');
-  console.log('  --capabilities <a,b> hire: comma-separated capability list');
+  console.log('  --capabilities <a,b> hire/assign: comma-separated capability list');
   console.log('  --sandbox <s>        hire/work: execution sandbox none|docker|podman (default none)');
   console.log('  --image <ref>        hire/work: container image the agent runs in (required for docker|podman)');
   console.log('  --env NAME=VALUE     hire/work: static env var for the harness (repeatable); persisted on hire, work extends/overrides');
@@ -4703,6 +5036,7 @@ function printUsage() {
   console.log('  --job-type <token>   work: extra job type to service alongside the rank×capability matrix (repeatable)');
   console.log('  --job-timeout <ms>   work: max harness runtime per job in ms (default 300000)');
   console.log('  --lock-grace <ms>    work: extra ms over --job-timeout for the broker activation lock (default 120000)');
+  console.log('  --poll-timeout <ms>  work: broker long-poll window per activateJobs request (default 30000; 0 = broker default, negative = immediate)');
   console.log('  --secret-resolver <r> work: secret resolver for task secretRefs (host; default host)');
   console.log('  --reap-age <ms>      work: age before a finished agent container/workspace is reaped (default 3600000)');
   console.log('  --reap-interval <ms> work: how often to sweep finished agent containers/workspaces (default 300000)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -42,19 +42,17 @@
   "devDependencies": {
     "@commitlint/cli": "^20.4.1",
     "@commitlint/config-conventional": "^20.4.1",
-    "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.6",
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.18.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.20.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.20.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.20.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.20.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.20.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.20.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.20.0"
   }
 }