c8ctl-plugin-nano 1.8.0 → 1.10.0

package/README.md

@@ -130,6 +130,135 @@ c8ctl nano set model-dir ~/bpmn-workspace
 This creates `~/bpmn-workspace/models/` and `~/bpmn-workspace/workers/`. Restart a
 running cluster for a workspace change to take effect.
 
+## CLI agent workers: `hire` / `work`
+
+Beyond BPMN service-task workers (code in the workspace `workers/` dir), the
+plugin can turn an interactive **CLI agent harness** (Copilot CLI, Claude CLI,
+`pi`, "little coder", …) into a Nano job worker.
+
+**`hire`** persists an agent *profile* — a name, a **rank**
+(`principal|senior|junior|decider`), the **command** that starts the CLI, a
+**model** name, and a list of **capabilities**:
+
+```bash
+# Interactive
+c8ctl nano hire
+
+# Or non-interactively
+c8ctl nano hire --name reviewer --rank senior --command copilot \
+  --model gpt-5 --capabilities code-review,testing
+
+# List profiles
+c8ctl nano hire --list
+```
+
+**`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
+capabilities `code-review, testing` the matrix is:
+
+| Token | Meaning |
+| --- | --- |
+| `senior` | rank alone |
+| `senior:code-review` | rank + one capability (spread) |
+| `senior:testing` | rank + one capability (spread) |
+| `senior:code-review+testing` | rank + all capabilities, sorted (combined) |
+
+so a BPMN service task can target a worker at any granularity by setting its job
+type to the matching token.
+
+```bash
+c8ctl nano work reviewer                     # poll for work until Ctrl-C
+c8ctl nano work reviewer --max-parallel 2 --job-timeout 600000
+```
+
+Each activated job runs the profile's command **once** (one-shot): the job is
+serialized to JSON and piped to the CLI's **stdin** —
+
+```json
+{ "jobKey": "...", "jobType": "senior:code-review", "processInstanceKey": "...",
+  "prompt": "<variables.prompt ?? variables.task>", "variables": {},
+  "profile": { "name": "reviewer", "rank": "senior", "model": "gpt-5",
+               "capabilities": ["code-review", "testing"] } }
+```
+
+and the profile/model are also exported as `AGENT_PROFILE`, `AGENT_RANK`,
+`AGENT_MODEL`, `AGENT_CAPABILITIES`, `AGENT_JOB_TYPE` env vars. On exit `0` the
+job is **completed** with `{ output: <stdout>, exitCode: 0 }` (captured output is
+capped at 1 MiB, with a `truncated` flag when exceeded); any other exit **fails**
+the job with a decremented retry count, and a job that outlives `--job-timeout`
+is killed. Profiles are stored in the plugin's `config.json` (see `c8ctl nano
+config`).
+
+> **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
+> shell-interpreted. Untrusted job data reaches the harness solely as stdin JSON
+> and `AGENT_*` env vars, never interpolated into the command line, so process
+> variables cannot inject shell commands.
+
+### Task envelope, sandboxes & disk hygiene
+
+For **agentic** jobs (an agent that clones a repo, works a task, pushes a
+branch) the job carries a structured **task envelope** under the reserved
+`io.nanobpm.agentTask` namespace. It is assembled from the job's static
+`customHeaders` (model-authored defaults) deep-merged with per-instance
+`variables` (**overrides win**), then normalized to schema v1 and included in the
+stdin payload as `task`:
+
+```jsonc
+{
+  "io.nanobpm.agentTask.repository.url": "https://github.com/o/r.git", // header
+  "io.nanobpm.agentTask.repository.ref": "main",
+  "io.nanobpm.agentTask.branch.push":    "true",
+  "io.nanobpm.agentTask.task.allowPr":   "false"
+}
+```
+
+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} }`.
+On completion the plugin writes an **output envelope** back under
+`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error}`).
+
+**Sandbox.** By default the command runs on the host (`--sandbox none`). Pass
+`--sandbox docker` (or `podman`) with an `--image` to run **each job in a
+throwaway container** instead:
+
+```bash
+c8ctl nano hire --name coder --rank senior --command "agent-harness" \
+  --sandbox docker --image ghcr.io/acme/agent:1
+c8ctl nano work coder                 # uses the profile's sandbox/image
+c8ctl nano work coder --sandbox docker --image ghcr.io/acme/agent:1   # or override
+```
+
+Containers are labelled (`nano.managed=1`, `nano.worker`, `nano.jobKey`,
+`nano.run=<uuid>`), log-capped (`max-size=10m max-file=3`), run with `--rm`, and
+a run that outlives `--job-timeout` is force-removed. The envelope is piped on
+the container's stdin exactly as on the host.
+
+**Secrets.** Secrets are referenced by **name**, never value. `setup.secretRefs`
+(and the repo/PR credential when `task.allowPr` is set — defaulting to
+`GITHUB_TOKEN` for GitHub) are resolved via a pluggable `--secret-resolver`
+(only `host`, reading `process.env`, is implemented) and forwarded into the
+container by name (`-e NAME`) so values never appear in argv or `docker inspect`.
+A missing required secret fails the job with a clear provisioning message.
+
+**Disk hygiene.** Container sandboxes get automatic cleanup so leaked
+containers can't fill the disk: a **label-scoped** reaper runs at worker startup
+and on an interval (`--reap-interval`, **milliseconds**, default `300000` = 5m),
+removing finished/`exited` containers older than `--reap-age` (**milliseconds**,
+default `3600000` = 1h) while **skipping any run still in flight** — it never
+touches containers it didn't create and never `system prune`s. A **disk-budget
+admission shed** fails (retryable) new jobs when the engine data root has less
+than `--min-free-mb` MB free (default `1024`).
+
+> Git provisioning (clone/branch/push), agent-opened PRs, and the
+> Vercel/Sandcastle provider are **increment 2** — the envelope names above are
+> frozen so the [nano-ide element-template pack](https://github.com/jwulf/nano-ide/issues/37)
+> can be built against this contract.
+
 ## Cleaning up disk
 
 ```bash

package/c8ctl-plugin.js

@@ -40,11 +40,14 @@ import {
   chmodSync,
   renameSync,
   realpathSync,
+  statfsSync,
 } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { homedir, platform as osPlatform } from 'node:os';
 import { join, isAbsolute, resolve as resolvePath, dirname, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
 import { platformForHost } from './platforms.mjs';
 
 const requireFromHere = createRequire(import.meta.url);
@@ -363,7 +366,7 @@ function launcherEnvMarkers(resolved) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'work'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -1293,6 +1296,908 @@ function showConfig() {
   console.log('  Change with: c8ctl nano set bin <path> | c8ctl nano set model-dir <path>');
 }
 
+// ---------------------------------------------------------------------------
+// hire / work — CLI agent harness workers.
+//
+// A "hire" is a persisted agent profile (name, rank, CLI command, model,
+// capabilities). "work <name>" turns that profile into a set of Nano job
+// workers: one per job-type in the rank×capability matrix. When a job is
+// activated, the profile's CLI command is spawned fresh (one-shot), fed the job
+// as JSON on stdin, and its stdout is returned as the job's `output` variable.
+// ---------------------------------------------------------------------------
+
+const RANKS = ['principal', 'senior', 'junior', 'decider'];
+
+/** Normalize a capability list: trim, drop empties, de-dupe, sort (canonical). */
+function normalizeCapabilities(input) {
+  const raw = Array.isArray(input)
+    ? input
+    : String(input || '').split(',');
+  return [...new Set(raw.map((c) => String(c).trim().toLowerCase()).filter(Boolean))].sort();
+}
+
+/** A profile name must be a safe, filesystem/token-friendly slug. */
+function isValidProfileName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name);
+}
+
+/**
+ * The job-type matrix a worker subscribes to, from a profile's rank
+ * and sorted capabilities [c1, c2, ...]:
+ *   - `rank`                 (rank alone)
+ *   - `rank:c1`, `rank:c2`   (rank + a single capability, "spread")
+ *   - `rank:c1+c2+...`       (rank + all capabilities combined; only when >1 cap)
+ * Delimiters: `:` separates rank from capabilities, `+` joins combined caps.
+ * Capabilities are sorted so the combined token is canonical/predictable.
+ */
+function jobTypeMatrix(rank, capabilities) {
+  const caps = normalizeCapabilities(capabilities);
+  const tokens = [rank];
+  for (const c of caps) tokens.push(`${rank}:${c}`);
+  if (caps.length > 1) tokens.push(`${rank}:${caps.join('+')}`);
+  return [...new Set(tokens)];
+}
+
+/** All persisted hire profiles, keyed by name. */
+function readHires() {
+  const cfg = readConfig();
+  // A JSON array is `typeof === 'object'` but drops string-keyed writes on
+  // JSON.stringify, so treat only plain objects as a valid hires map.
+  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();
+  if (!cfg.hires || typeof cfg.hires !== 'object' || Array.isArray(cfg.hires)) cfg.hires = {};
+  cfg.hires[profile.name] = profile;
+  writeConfig(cfg);
+}
+
+/**
+ * Validate and normalize a stored profile before use so a hand-edited or
+ * version-skewed config.json can't produce undefined job types or an invalid
+ * spawn. Returns the normalized profile, or a { error } describing the problem.
+ */
+function normalizeStoredProfile(name, profile) {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+    return { error: `profile "${name}" is not an object` };
+  }
+  const rank = String(profile.rank || '').trim().toLowerCase();
+  if (!RANKS.includes(rank)) {
+    return { error: `profile "${name}" has an invalid rank "${profile.rank}" (expected one of: ${RANKS.join(', ')})` };
+  }
+  const command = String(profile.command || '').trim();
+  if (!command) {
+    return { error: `profile "${name}" has no command to run` };
+  }
+  const sandbox = String(profile.sandbox || 'none').trim().toLowerCase();
+  if (!SANDBOXES.includes(sandbox)) {
+    return { error: `profile "${name}" has an invalid sandbox "${profile.sandbox}" (expected one of: ${SANDBOXES.join(', ')})` };
+  }
+  const image = typeof profile.image === 'string' ? profile.image.trim() : '';
+  if (CONTAINER_SANDBOXES.has(sandbox) && !image) {
+    return { error: `profile "${name}" uses sandbox "${sandbox}" but has no image` };
+  }
+  return {
+    profile: {
+      name,
+      rank,
+      command,
+      model: typeof profile.model === 'string' ? profile.model.trim() : '',
+      capabilities: normalizeCapabilities(profile.capabilities),
+      sandbox,
+      image,
+    },
+  };
+}
+
+/**
+ * hire — create (or overwrite) an agent profile. Interactive by default; every
+ * 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.
+ */
+async function hireWorker(req, flags) {
+  const logger = getLogger();
+
+  if (flags?.list) {
+    const hires = readHires();
+    const names = Object.keys(hires);
+    if (names.length === 0) {
+      logger.info('No hires yet. Create one with: c8ctl nano hire');
+      return;
+    }
+    logger.info('Hired agent profiles:');
+    for (const name of names.sort()) {
+      const p = hires[name];
+      logger.info(`  ${name}  [${p.rank}]  ${p.command}  (model: ${p.model || '-'}; caps: ${normalizeCapabilities(p.capabilities).join(', ') || '-'})`);
+    }
+    logger.info('');
+    logger.info('Put one to work with: c8ctl nano work <name>');
+    return;
+  }
+
+  // Seed from flags; prompt for anything still missing. Trim string flags so a
+  // stray space can't be persisted into config.json or the spawned command.
+  let name = flags?.name ? String(flags.name).trim() : req.positional[0];
+  let rank = flags?.rank ? String(flags.rank).trim().toLowerCase() : undefined;
+  let command = flags?.command !== undefined ? String(flags.command).trim() : undefined;
+  let model = flags?.model !== undefined ? String(flags.model).trim() : undefined;
+  let capabilities = flags?.capabilities !== undefined ? flags.capabilities : undefined;
+  let sandbox = flags?.sandbox !== undefined ? String(flags.sandbox).trim().toLowerCase() : undefined;
+  let image = flags?.image !== undefined ? String(flags.image).trim() : undefined;
+
+  const missingRequired = !name || !rank || !command;
+  const missingOptional = model === undefined || capabilities === undefined;
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+
+  // Non-interactively only name/rank/command are required; model and
+  // capabilities are optional (they default to empty), matching how the
+  // interactive prompts label them.
+  if (missingRequired && !interactive) {
+    logger.error('Non-interactive: provide at least --name, --rank and --command.');
+    logger.info('Example: c8ctl nano hire --name reviewer --rank senior --command copilot --model gpt-5 --capabilities code-review,testing');
+    process.exit(1);
+  }
+
+  if (interactive && (missingRequired || missingOptional)) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      console.log('Hire a CLI agent worker. Press Ctrl-C to cancel.');
+      console.log('');
+      while (!name) {
+        const ans = (await rl.question('Profile name: ')).trim();
+        if (isValidProfileName(ans)) { name = ans; break; }
+        console.log('  Please use letters, digits, dot, dash or underscore.');
+      }
+      while (!rank) {
+        const ans = (await rl.question(`Rank (${RANKS.join('|')}): `)).trim().toLowerCase();
+        if (RANKS.includes(ans)) { rank = ans; break; }
+        console.log(`  Rank must be one of: ${RANKS.join(', ')}`);
+      }
+      while (!command) {
+        const ans = (await rl.question('CLI command (e.g. copilot, claude, pi): ')).trim();
+        if (ans) { command = ans; break; }
+        console.log('  A command is required.');
+      }
+      if (model === undefined) {
+        model = (await rl.question('Model name (optional): ')).trim();
+      }
+      if (capabilities === undefined) {
+        capabilities = (await rl.question('Capabilities (comma-separated, optional): ')).trim();
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  // Optional fields default to empty when omitted (e.g. scripted invocations).
+  if (model === undefined) model = '';
+  if (capabilities === undefined) capabilities = '';
+  if (sandbox === undefined || sandbox === '') sandbox = 'none';
+  if (image === undefined) image = '';
+
+  if (!SANDBOXES.includes(sandbox)) {
+    logger.error(`Invalid --sandbox "${sandbox}". Use one of: ${SANDBOXES.join(', ')}`);
+    process.exit(1);
+  }
+  if (CONTAINER_SANDBOXES.has(sandbox) && !image) {
+    logger.error(`--sandbox ${sandbox} requires --image <ref> (the container image the agent runs in).`);
+    process.exit(1);
+  }
+
+  if (!isValidProfileName(name)) {
+    logger.error(`Invalid profile name "${name}". Use letters, digits, dot, dash or underscore.`);
+    process.exit(1);
+  }
+  if (!RANKS.includes(rank)) {
+    logger.error(`Invalid rank "${rank}". Must be one of: ${RANKS.join(', ')}`);
+    process.exit(1);
+  }
+  if (!command) {
+    logger.error('A CLI command is required.');
+    process.exit(1);
+  }
+
+  const existed = Boolean(readHires()[name]);
+  const profile = {
+    name,
+    rank,
+    command,
+    model: model || '',
+    capabilities: normalizeCapabilities(capabilities),
+    sandbox,
+    image: image || '',
+    createdAt: new Date().toISOString(),
+  };
+  writeHire(profile);
+
+  const matrix = jobTypeMatrix(profile.rank, profile.capabilities);
+  logger.info(`${existed ? 'Updated' : 'Hired'} "${name}" [${profile.rank}] → ${profile.command}`);
+  logger.info(`  model: ${profile.model || '(none)'}`);
+  logger.info(`  capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
+  logger.info(`  sandbox: ${profile.sandbox}${CONTAINER_SANDBOXES.has(profile.sandbox) ? ` (image ${profile.image})` : ''}`);
+  logger.info(`  job types (${matrix.length}): ${matrix.join('  ')}`);
+  logger.info(`Put it to work with: c8ctl nano work ${name}`);
+}
+
+/**
+ * Concatenate captured Buffer chunks into a UTF-8 string, dropping a trailing
+ * incomplete multibyte sequence (which the byte cap may have split) so decoding
+ * never emits a replacement char or pushes the string over the byte cap.
+ */
+function joinCapped(chunks) {
+  if (!chunks.length) return '';
+  let buf = Buffer.concat(chunks);
+  let i = buf.length - 1;
+  let cont = 0;
+  while (i >= 0 && (buf[i] & 0xc0) === 0x80 && cont < 3) { i -= 1; cont += 1; }
+  if (i >= 0) {
+    const lead = buf[i];
+    let needed;
+    if ((lead & 0x80) === 0x00) needed = 0;
+    else if ((lead & 0xe0) === 0xc0) needed = 1;
+    else if ((lead & 0xf0) === 0xe0) needed = 2;
+    else if ((lead & 0xf8) === 0xf0) needed = 3;
+    else needed = -1;
+    if (needed > 0 && cont < needed) buf = buf.subarray(0, i);
+  }
+  return buf.toString('utf8');
+}
+
+/**
+ * Kill a spawned child and its whole process tree. With `detached: true` on
+ * POSIX the child leads its own process group, so a negative PID signals every
+ * process in that group (shell wrapper + the actual harness command). Falls
+ * back to a plain child.kill() on Windows or if the group signal fails.
+ */
+function killTree(child) {
+  const pid = child.pid;
+  if (process.platform !== 'win32' && typeof pid === 'number') {
+    try { process.kill(-pid, 'SIGKILL'); return; } catch { /* fall through */ }
+  }
+  try { child.kill('SIGKILL'); } catch { /* already gone */ }
+}
+
+// ===========================================================================
+// Agent task envelope + sandboxed execution (issue #8, increment 1)
+// ===========================================================================
+
+// Reserved namespaces. The INPUT envelope is assembled from the job's static
+// customHeaders (model-authored defaults) deep-merged with per-instance
+// variables (overrides win), then normalized/coerced to schema v1. The OUTPUT
+// envelope is written back on the job's completion variables.
+const AGENT_TASK_NS = 'io.nanobpm.agentTask';
+const AGENT_RESULT_KEY = 'io.nanobpm.agentResult';
+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.
+const RESULT_ENVELOPE_SCHEMA_VERSION = 1;
+const SANDBOXES = ['none', 'docker', 'podman'];
+// Only container-based sandboxes need an image / disk hygiene / a runtime bin.
+const CONTAINER_SANDBOXES = new Set(['docker', 'podman']);
+
+function coerceBool(v, dflt = false) {
+  if (typeof v === 'boolean') return v;
+  if (v == null) return dflt;
+  const s = String(v).trim().toLowerCase();
+  if (['true', '1', 'yes', 'on'].includes(s)) return true;
+  if (['false', '0', 'no', 'off', ''].includes(s)) return false;
+  return dflt;
+}
+
+function coerceInt(v, dflt) {
+  if (v == null || v === '') return dflt;
+  const n = Number.parseInt(String(v), 10);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(base, over) {
+  if (!isPlainObject(base)) return isPlainObject(over) ? deepMerge({}, over) : over;
+  const out = { ...base };
+  if (!isPlainObject(over)) return out;
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    out[k] = isPlainObject(v) && isPlainObject(out[k]) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+function setPath(obj, path, value) {
+  let cur = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const k = path[i];
+    if (!isPlainObject(cur[k])) cur[k] = {};
+    cur = cur[k];
+  }
+  cur[path[path.length - 1]] = value;
+}
+
+// Collect the reserved namespace out of a flat key→value map (customHeaders or
+// variables). Supports both a single `io.nanobpm.agentTask` key whose value is
+// a JSON string/object, AND flattened dotpath keys like
+// `io.nanobpm.agentTask.repository.ref` (element templates emit the latter).
+function collectEnvelopeFrom(source) {
+  const out = {};
+  if (!isPlainObject(source)) return out;
+  const whole = source[AGENT_TASK_NS];
+  if (whole != null) {
+    let val = whole;
+    if (typeof whole === 'string') {
+      try { val = JSON.parse(whole); } catch { val = undefined; }
+    }
+    if (isPlainObject(val)) Object.assign(out, deepMerge(out, val));
+  }
+  const prefix = `${AGENT_TASK_NS}.`;
+  for (const [key, value] of Object.entries(source)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (!rest) continue;
+    setPath(out, rest.split('.'), value);
+  }
+  return out;
+}
+
+// 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) {
+  const raw = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables));
+  const str = (v) => (v == null ? undefined : String(v));
+  const env = {
+    // Normalization always emits the v1 shape, so the version is forced to v1
+    // (the raw input version is only a hint about how the author authored it).
+    schemaVersion: TASK_ENVELOPE_SCHEMA_VERSION,
+  };
+
+  const repo = raw.repository;
+  if (isPlainObject(repo) && str(repo.url)) {
+    env.repository = {
+      provider: str(repo.provider) || 'github',
+      url: str(repo.url),
+      ref: str(repo.ref),
+      depth: coerceInt(repo.depth, undefined),
+      submodules: coerceBool(repo.submodules, false),
+      authRef: str(repo.authRef),
+    };
+  }
+
+  const branch = isPlainObject(raw.branch) ? raw.branch : {};
+  env.branch = {
+    base: str(branch.base),
+    create: str(branch.create),
+    push: coerceBool(branch.push, true),
+  };
+
+  const setup = isPlainObject(raw.setup) ? raw.setup : {};
+  env.setup = {
+    commands: Array.isArray(setup.commands) ? setup.commands.map(String) : [],
+    env: isPlainObject(setup.env) ? setup.env : {},
+    secretRefs: Array.isArray(setup.secretRefs) ? setup.secretRefs.map(String) : [],
+  };
+
+  const task = isPlainObject(raw.task) ? raw.task : {};
+  env.task = {
+    prompt: str(task.prompt) ?? str(variables?.prompt) ?? str(variables?.task),
+    promptFile: str(task.promptFile),
+    maxIterations: coerceInt(task.maxIterations, undefined),
+    timeoutMs: coerceInt(task.timeoutMs, undefined),
+    allowPr: coerceBool(task.allowPr, false),
+    prBase: str(task.prBase),
+  };
+
+  return env;
+}
+
+// ---- Secret resolution (pluggable; only host-env implemented for now) ------
+// 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`.
+const hostEnvSecretResolver = {
+  kind: 'host',
+  resolve(name) {
+    const v = process.env[name];
+    return v == null || v === '' ? undefined : v;
+  },
+};
+
+function makeSecretResolver(kind) {
+  const k = (kind || 'host').trim().toLowerCase();
+  if (k === 'host' || k === '') return hostEnvSecretResolver;
+  return null; // unknown → caller reports a clear error
+}
+
+// Resolve the names a job needs (setup.secretRefs, plus the repo/PR credential
+// when allowPr). Returns resolved values + a list of names that were missing so
+// the caller can fail the job with a clear provisioning error.
+function resolveJobSecrets(resolver, envelope) {
+  const names = new Set();
+  for (const n of envelope.setup?.secretRefs || []) if (n) names.add(n);
+  if (envelope.task?.allowPr) {
+    const provider = envelope.repository?.provider || 'github';
+    const authRef = envelope.repository?.authRef || (provider === 'github' ? 'GITHUB_TOKEN' : undefined);
+    if (authRef) names.add(authRef);
+  }
+  const resolved = {};
+  const missing = [];
+  for (const name of names) {
+    const v = resolver.resolve(name);
+    if (v === undefined) missing.push(name);
+    else resolved[name] = v;
+  }
+  return { resolved, missing, names: [...names] };
+}
+
+// ---- Disk hygiene (container sandboxes only) -------------------------------
+const CONTAINER_LABEL = 'nano.managed=1';
+
+function containerEngineAvailable(engine) {
+  try {
+    const r = spawnSync(engine, ['version', '--format', '{{.Server.Version}}'], { encoding: 'utf8', timeout: 10_000 });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// Resolve the container engine's data root. Returns null when it can't be
+// determined so the caller can fail OPEN (never fall back to an unrelated path
+// like the OS temp dir, which would shed on the wrong filesystem's free space).
+function dockerRootDir(engine) {
+  try {
+    const r = spawnSync(engine, ['info', '-f', '{{.DockerRootDir}}'], { encoding: 'utf8', timeout: 10_000 });
+    const dir = (r.stdout || '').trim();
+    if (r.status === 0 && dir) return dir;
+  } catch { /* fall through */ }
+  return null;
+}
+
+// Fail-open disk-budget check: shed work when free space on the engine's data
+// root drops below the configured floor (mirrors nano's admission-shed pattern).
+function diskBudgetOk(engine, minFreeBytes) {
+  if (!minFreeBytes || minFreeBytes <= 0) return { ok: true, free: null };
+  try {
+    if (typeof statfsSync !== 'function') return { ok: true, free: null };
+    const root = dockerRootDir(engine);
+    if (!root) return { ok: true, free: null }; // can't resolve the real root → fail open
+    const st = statfsSync(root);
+    const free = st.bavail * st.bsize;
+    return { ok: free >= minFreeBytes, free };
+  } catch {
+    return { ok: true, free: null }; // never block work on a stat failure
+  }
+}
+
+// Reap our own leaked/finished containers. Label-scoped (never touches anything
+// we didn't create — safe on shared hosts, NEVER `system prune -a`), age-gated,
+// and skips any run id still in flight.
+function reapAgentContainers(engine, { maxAgeMs = 0, liveRunIds = new Set() } = {}) {
+  let reaped = 0;
+  try {
+    const fmt = '{{.ID}}\t{{.Label "nano.run"}}\t{{.State}}\t{{.CreatedAt}}';
+    const r = spawnSync(engine, ['ps', '-a', '--filter', `label=${CONTAINER_LABEL}`, '--format', fmt], { encoding: 'utf8', timeout: 15_000 });
+    if (r.status !== 0) return { reaped, error: (r.stderr || '').trim() || 'ps failed' };
+    const now = Date.now();
+    for (const line of (r.stdout || '').split('\n')) {
+      if (!line.trim()) continue;
+      const [id, run, state, created] = line.split('\t');
+      if (run && liveRunIds.has(run)) continue; // in-flight; leave it
+      if (!/exited|dead|created/i.test(state || '')) continue; // only finished/stuck
+      if (maxAgeMs > 0) {
+        const createdMs = Date.parse(created || '');
+        if (Number.isFinite(createdMs) && now - createdMs < maxAgeMs) continue;
+      }
+      const rm = spawnSync(engine, ['rm', '-f', id], { timeout: 15_000 });
+      if (rm.status === 0) reaped++;
+    }
+  } catch (err) {
+    return { reaped, error: err.message };
+  }
+  return { reaped };
+}
+
+// ---- One-shot capture (shared by host + container executors) ---------------
+const MAX_CAPTURE_BYTES = 1_048_576; // 1 MiB per stream
+
+// Spawn a child, pipe `stdinData`, capture byte-capped stdout/stderr, enforce a
+// timeout (invoking `onTimeout(child)` to tear the child down), and resolve to a
+// uniform result. Used by both the host and container executors.
+function spawnCaptureOneShot({ command, args = [], shell = false, detached = false, env, stdinData, timeoutMs, onTimeout }) {
+  return new Promise((resolve) => {
+    let child;
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let settled = false;
+    let timer = null;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+
+    try {
+      child = spawn(command, args, { shell, detached, stdio: ['pipe', 'pipe', 'pipe'], env });
+    } catch (err) {
+      finish({ ok: false, exitCode: null, stdout: '', stderr: '', error: err.message, truncated: false, stderrTruncated: false });
+      return;
+    }
+
+    timer = timeoutMs && timeoutMs > 0
+      ? setTimeout(() => {
+          try { if (onTimeout) onTimeout(child); } catch { /* best effort */ }
+          finish({ ok: false, exitCode: null, stdout: joinCapped(stdoutChunks), stderr: joinCapped(stderrChunks), error: `timed out after ${timeoutMs}ms`, timedOut: true, truncated: stdoutTruncated, stderrTruncated });
+        }, timeoutMs)
+      : null;
+
+    child.stdout.on('data', (d) => {
+      const buf = Buffer.isBuffer(d) ? d : Buffer.from(d);
+      const remaining = MAX_CAPTURE_BYTES - stdoutBytes;
+      if (remaining <= 0) { stdoutTruncated = true; return; }
+      if (buf.length > remaining) { stdoutChunks.push(buf.subarray(0, remaining)); stdoutBytes = MAX_CAPTURE_BYTES; stdoutTruncated = true; }
+      else { stdoutChunks.push(buf); stdoutBytes += buf.length; }
+    });
+    child.stderr.on('data', (d) => {
+      const buf = Buffer.isBuffer(d) ? d : Buffer.from(d);
+      const remaining = MAX_CAPTURE_BYTES - stderrBytes;
+      if (remaining <= 0) { stderrTruncated = true; return; }
+      if (buf.length > remaining) { stderrChunks.push(buf.subarray(0, remaining)); stderrBytes = MAX_CAPTURE_BYTES; stderrTruncated = true; }
+      else { stderrChunks.push(buf); stderrBytes += buf.length; }
+    });
+
+    child.on('error', (err) => {
+      finish({ ok: false, exitCode: null, stdout: joinCapped(stdoutChunks), stderr: joinCapped(stderrChunks), error: err.message, truncated: stdoutTruncated, stderrTruncated });
+    });
+    child.on('close', (code, signal) => {
+      finish({ ok: code === 0, exitCode: code, signal: signal ?? null, stdout: joinCapped(stdoutChunks), stderr: joinCapped(stderrChunks), truncated: stdoutTruncated, stderrTruncated });
+    });
+
+    child.stdin.on('error', () => {});
+    try {
+      if (stdinData != null) child.stdin.write(stdinData);
+      child.stdin.end();
+    } catch { /* 'error' handler resolves on failure */ }
+  });
+}
+
+function buildAgentPayload(profile, job, envelope) {
+  const variables = job.variables && typeof job.variables === 'object' ? job.variables : {};
+  return {
+    jobKey: job.jobKey,
+    jobType: job.type,
+    processInstanceKey: job.processInstanceKey ?? null,
+    elementInstanceKey: job.elementInstanceKey ?? null,
+    elementId: job.elementId ?? null,
+    bpmnProcessId: job.bpmnProcessId ?? job.processDefinitionId ?? null,
+    prompt: envelope?.task?.prompt ?? variables.prompt ?? variables.task ?? null,
+    task: envelope || null,
+    variables,
+    customHeaders: job.customHeaders ?? {},
+    profile: {
+      name: profile.name,
+      rank: profile.rank,
+      model: profile.model,
+      capabilities: profile.capabilities,
+    },
+  };
+}
+
+function baseAgentEnv(profile, job) {
+  return {
+    AGENT_PROFILE: profile.name,
+    AGENT_RANK: profile.rank,
+    AGENT_MODEL: profile.model || '',
+    AGENT_CAPABILITIES: (profile.capabilities || []).join(','),
+    AGENT_JOB_TYPE: String(job.type ?? ''),
+  };
+}
+
+/**
+ * Run a single activated job through the profile's CLI command (one-shot),
+ * dispatching on the profile's sandbox:
+ *   - none            → spawn the command on the host (legacy behaviour).
+ *   - docker | podman → `run --rm` a labelled, log-capped container, piping the
+ *                       task envelope on stdin; a run that outlives the timeout
+ *                       is force-removed so it never leaks a slot or disk.
+ * Both paths resolve to the same result contract.
+ */
+function runAgentJob(profile, job, opts = {}) {
+  const { timeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [] } = opts;
+  const payload = JSON.stringify(buildAgentPayload(profile, job, envelope));
+  const agentEnv = baseAgentEnv(profile, job);
+
+  if (!CONTAINER_SANDBOXES.has(sandbox)) {
+    return spawnCaptureOneShot({
+      command: profile.command,
+      shell: true,
+      // Own process group so the timeout handler can kill the whole tree.
+      detached: process.platform !== 'win32',
+      env: { ...process.env, ...agentEnv, ...secretEnv },
+      stdinData: payload,
+      timeoutMs,
+      onTimeout: (child) => killTree(child),
+    });
+  }
+
+  const engine = sandbox;
+  const containerName = `nano-${runId}`;
+  // Forward env by NAME only (`-e NAME`) so secret VALUES stay out of argv and
+  // `docker inspect`; docker reads the value from our child's environment.
+  const envArgs = [];
+  for (const k of Object.keys(agentEnv)) envArgs.push('-e', k);
+  for (const n of passThroughSecretNames) envArgs.push('-e', n);
+  const setupEnv = isPlainObject(envelope?.setup?.env) ? envelope.setup.env : {};
+  const setupEnvValues = {};
+  for (const [k, v] of Object.entries(setupEnv)) { envArgs.push('-e', k); setupEnvValues[k] = String(v); }
+
+  const args = [
+    'run', '--rm', '-i',
+    '--name', containerName,
+    '--label', CONTAINER_LABEL,
+    '--label', `nano.worker=${profile.name}`,
+    '--label', `nano.jobKey=${job.jobKey}`,
+    '--label', `nano.run=${runId}`,
+    '--log-opt', 'max-size=10m',
+    '--log-opt', 'max-file=3',
+    ...envArgs,
+    image,
+    'sh', '-c', profile.command,
+  ];
+
+  return spawnCaptureOneShot({
+    command: engine,
+    args,
+    shell: false,
+    env: { ...process.env, ...agentEnv, ...secretEnv, ...setupEnvValues },
+    stdinData: payload,
+    timeoutMs,
+    onTimeout: (child) => {
+      try { spawnSync(engine, ['rm', '-f', containerName], { timeout: 15_000 }); } catch { /* best effort */ }
+      try { killTree(child); } catch { /* best effort */ }
+    },
+  });
+}
+
+// Shape the io.nanobpm.agentResult output envelope. branch/commits/pr are
+// reserved for increment 2 (git provisioning); increment 1 reports execution.
+function buildResultEnvelope(result, { sandbox, image }) {
+  const status = result.ok ? 'completed' : (result.timedOut ? 'timedOut' : 'failed');
+  return {
+    schemaVersion: RESULT_ENVELOPE_SCHEMA_VERSION,
+    status,
+    sandbox,
+    image: image || null,
+    output: result.stdout ?? '',
+    truncated: !!result.truncated,
+    stderrTruncated: !!result.stderrTruncated,
+    exitCode: result.exitCode ?? null,
+    signal: result.signal ?? null,
+    error: result.error ?? null,
+  };
+}
+
+/**
+ * work — turn a hire profile into live Nano job workers (one per job-type in
+ * the rank×capability matrix) and poll for work in the foreground until Ctrl-C.
+ * Uses the c8ctl-provided SDK client (globalThis.c8ctl.createClient()).
+ */
+async function workAgent(req, flags) {
+  const logger = getLogger();
+  const name = flags?.name ? String(flags.name).trim() : req.positional[0];
+
+  if (!name) {
+    const hires = readHires();
+    const names = Object.keys(hires).sort();
+    logger.error('Usage: c8ctl nano work <profileName>');
+    if (names.length > 0) logger.info(`Profiles: ${names.join(', ')}`);
+    else logger.info('No hires yet. Create one with: c8ctl nano hire');
+    process.exit(1);
+  }
+
+  const stored = readHires()[name];
+  if (!stored) {
+    logger.error(`No hire named "${name}". List profiles with: c8ctl nano hire --list`);
+    process.exit(1);
+  }
+  const normalized = normalizeStoredProfile(name, stored);
+  if (normalized.error) {
+    logger.error(`Cannot work "${name}": ${normalized.error}. Re-create it with: c8ctl nano hire`);
+    process.exit(1);
+  }
+  const profile = normalized.profile;
+
+  if (!globalThis.c8ctl || typeof globalThis.c8ctl.createClient !== 'function') {
+    logger.error('work requires the c8ctl runtime (createClient). Run it via the c8ctl CLI.');
+    process.exit(1);
+  }
+
+  const intFlag = (v, dflt) => {
+    const n = Number.parseInt(String(v ?? ''), 10);
+    return Number.isFinite(n) && n > 0 ? n : dflt;
+  };
+  const maxParallelJobs = intFlag(flags?.['max-parallel'], 1);
+  const jobTimeoutMs = intFlag(flags?.['job-timeout'], 5 * 60_000);
+
+  // Sandbox: flag overrides the stored profile default. `none` runs on the host
+  // (legacy); `docker`/`podman` run each job in a throwaway labelled container.
+  const sandbox = String(flags?.sandbox ?? profile.sandbox ?? 'none').trim().toLowerCase();
+  if (!SANDBOXES.includes(sandbox)) {
+    logger.error(`Invalid --sandbox "${sandbox}". Use one of: ${SANDBOXES.join(', ')}`);
+    process.exit(1);
+  }
+  const image = flags?.image ? String(flags.image).trim() : (profile.image || '');
+  const isContainer = CONTAINER_SANDBOXES.has(sandbox);
+  if (isContainer && !image) {
+    logger.error(`--sandbox ${sandbox} requires an --image (or hire the profile with --image).`);
+    process.exit(1);
+  }
+
+  const secretResolver = makeSecretResolver(flags?.['secret-resolver']);
+  if (!secretResolver) {
+    logger.error(`Unknown --secret-resolver "${flags?.['secret-resolver']}". Only "host" is supported.`);
+    process.exit(1);
+  }
+
+  // Disk-hygiene knobs (container sandboxes only). Reaper age + interval and the
+  // free-space admission floor mirror nano's own disk-budget/reaper patterns.
+  const reapAgeMs = intFlag(flags?.['reap-age'], 60 * 60_000); // 1h
+  const reapIntervalMs = intFlag(flags?.['reap-interval'], 5 * 60_000); // 5m
+  const minFreeBytes = flags?.['min-free-mb'] != null
+    ? Math.max(0, intFlag(flags['min-free-mb'], 0)) * 1_048_576
+    : 1_073_741_824; // 1 GiB default floor
+
+  // Tracks run ids currently executing so the reaper never removes a live
+  // container out from under an in-flight job.
+  const liveRunIds = new Set();
+  let reaperTimer = null;
+
+  if (isContainer) {
+    if (!containerEngineAvailable(sandbox)) {
+      logger.error(`--sandbox ${sandbox} selected but "${sandbox}" is not available/running on this host.`);
+      process.exit(1);
+    }
+    // Age-gate the startup sweep too (not maxAgeMs:0): on a shared host other
+    // worker processes may have just-created containers not yet in liveRunIds,
+    // so only reap ones older than --reap-age, matching the interval reaper.
+    const initial = reapAgentContainers(sandbox, { maxAgeMs: reapAgeMs, liveRunIds });
+    if (initial.reaped > 0) logger.info(`Reaped ${initial.reaped} leftover agent container(s) at startup.`);
+    if (initial.error) logger.warn(`Startup reap warning: ${initial.error}`);
+    reaperTimer = setInterval(() => {
+      const r = reapAgentContainers(sandbox, { maxAgeMs: reapAgeMs, liveRunIds });
+      if (r.reaped > 0) logger.info(`Reaper removed ${r.reaped} finished agent container(s).`);
+    }, reapIntervalMs);
+    if (typeof reaperTimer.unref === 'function') reaperTimer.unref();
+  }
+
+  const matrix = jobTypeMatrix(profile.rank, profile.capabilities);
+  const camunda = globalThis.c8ctl.createClient();
+
+  logger.info(`Putting "${name}" [${profile.rank}] to work → ${profile.command}`);
+  logger.info(`  model: ${profile.model || '(none)'}; capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
+  logger.info(`  sandbox: ${sandbox}${isContainer ? ` (image ${image})` : ''}`);
+  logger.info(`  listening on ${matrix.length} job type(s): ${matrix.join('  ')}`);
+  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobTimeoutMs}ms`);
+  logger.info('Polling for work — press Ctrl-C to stop.');
+
+  const workers = matrix.map((jobType) =>
+    camunda.createJobWorker({
+      jobType,
+      workerName: `${name}:${jobType}`,
+      maxParallelJobs,
+      jobTimeoutMs,
+      jobHandler: async (job) => {
+        logger.info(`[${jobType}] job ${job.jobKey} (instance ${job.processInstanceKey ?? '-'}) → ${profile.command}`);
+
+        // Disk-budget admission shed: if the engine data root is below the free
+        // floor, don't start a container — fail (retryable) so work sheds until
+        // the reaper/host frees space.
+        if (isContainer) {
+          const budget = diskBudgetOk(sandbox, minFreeBytes);
+          if (!budget.ok) {
+            const freeMb = budget.free != null ? Math.round(budget.free / 1_048_576) : '?';
+            const retries = Math.max(0, (Number(job.retries) || 1) - 1);
+            logger.warn(`[${jobType}] job ${job.jobKey} shed — low disk (${freeMb}MB free); retries left ${retries}`);
+            return job.fail({ errorMessage: `disk budget exceeded (only ${freeMb}MB free)`, retries, retryBackOff: 30_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 { resolved, missing, names } = resolveJobSecrets(secretResolver, envelope);
+        if (missing.length > 0) {
+          const retries = Math.max(0, (Number(job.retries) || 1) - 1);
+          const msg = `missing secret(s): ${missing.join(', ')} (resolver: ${secretResolver.kind})`;
+          logger.warn(`[${jobType}] job ${job.jobKey} not provisioned — ${msg}; retries left ${retries}`);
+          return job.fail({ errorMessage: msg, retries });
+        }
+
+        const runId = randomUUID();
+        if (isContainer) liveRunIds.add(runId);
+        let result;
+        try {
+          result = await runAgentJob(profile, job, {
+            timeoutMs: jobTimeoutMs,
+            envelope,
+            sandbox,
+            image,
+            runId,
+            secretEnv: resolved,
+            passThroughSecretNames: names,
+          });
+        } finally {
+          if (isContainer) liveRunIds.delete(runId);
+        }
+
+        const resultEnvelope = buildResultEnvelope(result, { sandbox, image });
+        if (result.ok) {
+          logger.info(`[${jobType}] job ${job.jobKey} complete (exit 0)${result.truncated ? ' [output truncated]' : ''}`);
+          return job.complete({
+            [AGENT_RESULT_KEY]: resultEnvelope,
+            output: result.stdout,
+            exitCode: 0,
+            agent: profile.name,
+            truncated: Boolean(result.truncated),
+          });
+        }
+        const retries = Math.max(0, (Number(job.retries) || 1) - 1);
+        const detail = result.error
+          || (result.stderr || '').trim() + (result.stderrTruncated && (result.stderr || '').trim() ? ' [stderr truncated]' : '')
+          || (result.signal ? `terminated by signal ${result.signal}` : `exit code ${result.exitCode}`);
+        logger.warn(`[${jobType}] job ${job.jobKey} failed (${detail}); retries left ${retries}`);
+        return job.fail({
+          errorMessage: `agent "${profile.name}" failed: ${detail}`.slice(0, 2000),
+          retries,
+          variables: { [AGENT_RESULT_KEY]: resultEnvelope },
+        });
+      },
+    }),
+  );
+
+  // 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 (reaperTimer) clearInterval(reaperTimer);
+      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;
+          }
+        }),
+      );
+      if (stopFailures > 0) {
+        logger.warn(`${stopFailures} of ${workers.length} worker(s) did not stop cleanly; some connections may still be open.`);
+      } else {
+        logger.info('All workers stopped.');
+      }
+      resolve();
+    };
+    process.once('SIGINT', () => { stop('SIGINT'); });
+    process.once('SIGTERM', () => { stop('SIGTERM'); });
+  });
+}
+
 // ---------------------------------------------------------------------------
 // update — pull a new nanobpmn release onto a machine with an existing install.
 // The plugin (and the bundled server binary, shipped via the matching platform
@@ -2517,6 +3422,27 @@ 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 {
+  normalizeTaskEnvelope,
+  collectEnvelopeFrom,
+  coerceBool,
+  coerceInt,
+  deepMerge,
+  resolveJobSecrets,
+  makeSecretResolver,
+  hostEnvSecretResolver,
+  buildAgentPayload,
+  buildResultEnvelope,
+  reapAgentContainers,
+  diskBudgetOk,
+  containerEngineAvailable,
+  runAgentJob,
+  normalizeStoredProfile,
+  jobTypeMatrix,
+  AGENT_TASK_NS,
+  AGENT_RESULT_KEY,
+  SANDBOXES,
+};
 
 export const metadata = {
   name: 'c8ctl-plugin-nano',
@@ -2548,6 +3474,12 @@ export const metadata = {
         { 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 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 --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 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' },
       ],
     },
     processos: {
@@ -2589,6 +3521,20 @@ 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)' },
+      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)' },
+      model: { type: 'string', description: 'hire: model name passed to the harness (AGENT_MODEL)' },
+      capabilities: { type: 'string', description: 'hire: 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)' },
+      'secret-resolver': { type: 'string', description: 'work: secret resolver for task secretRefs (host = process env; default host)' },
+      'reap-age': { type: 'string', description: 'work: age in ms before a finished agent container is reaped (default 3600000)' },
+      'reap-interval': { type: 'string', description: 'work: how often to sweep finished agent containers in ms (default 300000)' },
+      'min-free-mb': { type: 'string', description: 'work: shed jobs when the engine data root has less than this many MB free (default 1024)' },
+      list: { type: 'boolean', description: 'hire: list existing agent profiles instead of creating one' },
+      '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)' },
     },
     handler: async (args, flags) => {
       const logger = getLogger();
@@ -2637,6 +3583,12 @@ export const commands = {
           case 'update':
             updatePlugin(req);
             break;
+          case 'hire':
+            await hireWorker(req, flags);
+            break;
+          case 'work':
+            await workAgent(req, flags);
+            break;
         }
       } catch (error) {
         logger.error(`nano ${req.subcommand} failed: ${error instanceof Error ? error.message : error}`);
@@ -2725,6 +3677,8 @@ function printUsage() {
   console.log('  c8ctl nano set <bin|model-dir> <path>');
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
+  console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--list]');
+  console.log('  c8ctl nano work <profileName> [--max-parallel <n>] [--job-timeout <ms>] [--sandbox none|docker|podman] [--image <ref>] [--secret-resolver host] [--min-free-mb <n>]');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -2738,6 +3692,8 @@ function printUsage() {
   console.log('  set      Persist a setting: "bin <path>" or "model-dir <path>"');
   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('  work     Run a hired profile as Nano job workers, polling for work until Ctrl-C');
   console.log('');
   console.log('Options:');
   console.log('  <nodes>              Number of nodes to start (default 1)');
@@ -2753,6 +3709,20 @@ 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('  --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('  --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('  --list               hire: list existing agent profiles instead of creating one');
+  console.log('  --max-parallel <n>   work: max concurrent jobs per worker (default 1)');
+  console.log('  --job-timeout <ms>   work: max harness runtime per job in ms (default 300000)');
+  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 is reaped (default 3600000)');
+  console.log('  --reap-interval <ms> work: how often to sweep finished agent containers (default 300000)');
+  console.log('  --min-free-mb <n>    work: shed jobs when the engine data root has < this many MB free (default 1024)');
   console.log('');
   console.log('Persistent assets:');
   console.log('  Models and workers live in the workspace dir (NANOBPMN_WORKSPACE_DIR),');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -27,7 +27,7 @@
   ],
   "scripts": {
     "lint": "node --check c8ctl-plugin.js",
-    "test": "node --check c8ctl-plugin.js"
+    "test": "node --check c8ctl-plugin.js && node --test"
   },
   "license": "MIT",
   "engines": {
@@ -49,12 +49,12 @@
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.8.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.8.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.8.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.8.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.8.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.8.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.8.0"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.10.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.10.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.10.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.10.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.10.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.10.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.10.0"
   }
 }