c8ctl-plugin-nano 1.42.0 → 1.43.0

package/c8ctl-plugin.js

@@ -482,7 +482,7 @@ function launcherEnvMarkers(resolved) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'unset', 'config', 'update', 'hire', 'assign', 'work', 'supervisor'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'unset', 'config', 'update', 'hire', 'assign', 'work', 'supervisor', 'workforce'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -1629,6 +1629,10 @@ function normalizeArgList(input) {
   const out = [];
   for (const item of list) {
     if (item == null) continue;
+    // A value-less string flag (e.g. a bare `--arg` with no following value) is
+    // coerced to boolean `true` by the flag layer. That is never a real arg, so
+    // drop it rather than persist the misleading literal token "true".
+    if (typeof item === 'boolean') continue;
     const s = String(item);
     if (s.length === 0) continue;
     out.push(s);
@@ -1636,6 +1640,17 @@ function normalizeArgList(input) {
   return out;
 }
 
+// True when a repeatable `--arg` flag contains a value-less occurrence: a bare
+// `--arg` with no following value arrives as boolean `true` from the flag layer.
+// Such an invocation is malformed — normalizeArgList would silently drop it,
+// making it look like the intended arg was accepted — so callers reject it up
+// front rather than let it be a silent no-op.
+function hasValuelessArg(argFlag) {
+  if (argFlag === undefined) return false;
+  const items = Array.isArray(argFlag) ? argFlag : [argFlag];
+  return items.some((a) => a === true);
+}
+
 // POSIX single-quote a string so it survives `sh -c`/shell:true as one literal
 // argv token, no matter what it contains (spaces, $, quotes, globs). Empty
 // string → ''. This is what keeps structured `--arg` values injection-safe even
@@ -1968,6 +1983,12 @@ async function hireWorker(req, flags) {
   let permission = flags?.permission !== undefined ? String(flags.permission).trim().toLowerCase() : undefined;
   // Structured command-line switches appended to the command when spawned, e.g.
   // `--arg --allow-all` for `copilot`. Repeatable; each --arg is one argv token.
+  // A value-less `--arg` (bare flag, boolean `true`) is a malformed invocation —
+  // reject it up front rather than silently drop it (mirrors workforce add).
+  if (hasValuelessArg(flags?.arg)) {
+    logger.error('--arg requires a value (e.g. --arg "--allow-all").');
+    process.exit(1);
+  }
   const commandArgs = normalizeArgList(flags?.arg);
   const envFromFlags = flags?.env !== undefined;
   const { env: profileEnv, errors: envErrors } = parseEnvPairs(flags?.env);
@@ -3961,12 +3982,12 @@ function spawnCapturePty({ command, args = [], cwd, env, stdinData, timeoutMs, i
 }
 
 // ---- ACP capture (C3 #110 — the third harness path, "minimal mode") ---------
-// Some ACP agents are native (`copilot --acp`, `opencode acp`), some ride an
-// adapter (`claude-agent-acp`, `pi-acp`). In every case the profile's command +
-// `--arg`s already assemble the ACP invocation; we only append a default `--acp`
-// switch when the assembled line doesn't already select ACP, so a native/adapter
-// invocation is never doubled. This mirrors how the pipe path spawns the line
-// under a shell.
+// Some ACP agents are native (`copilot --acp`, `qwen --experimental-acp`,
+// `opencode acp`), some ride an adapter (`claude-code-acp`, `pi-acp`). In every
+// case the profile's command + `--arg`s already assemble the ACP invocation; we
+// only append a default `--acp` switch when the assembled line doesn't already
+// select ACP, so a native/adapter invocation is never doubled. This mirrors how
+// the pipe path spawns the line under a shell.
 function ensureAcpFlag(commandLine) {
   // Detection must survive buildAgentCommandLine()'s POSIX single-quoting: a
   // structured `--arg acp` (or `--arg --acp`) lands here as the quoted token
@@ -3977,21 +3998,64 @@ function ensureAcpFlag(commandLine) {
   //   - a native ACP selector `acp`/`-acp`/`--acp` (subcommand or switch) as a
   //     WHOLE token, in ANY position (it may be the command or an argument), or
   //   - an adapter command whose basename ends in `-acp` (claude-agent-acp,
-  //     pi-acp) — but ONLY the command token (first token), since an *argument*
+  //     pi-acp) — but ONLY the command token (the first token past any leading
+  //     env-assignment prefix, see commandIndex below), since an *argument*
   //     that merely ends in `-acp` (e.g. `--model foo-acp`) is not an ACP
   //     selector. Matching whole tokens/basenames (not a substring) also avoids
   //     the false positive of a path that merely contains `/acp/`.
-  const tokens = commandLine.match(/'(?:[^']|'\\'')*'|"(?:[^"\\]|\\.)*"|\S+/g) || [];
-  for (let i = 0; i < tokens.length; i++) {
-    let tok = tokens[i];
-    if (tok.length >= 2 && tok.startsWith("'") && tok.endsWith("'")) {
-      tok = tok.slice(1, -1).replace(/'\\''/g, "'");
-    } else if (tok.length >= 2 && tok.startsWith('"') && tok.endsWith('"')) {
-      tok = tok.slice(1, -1).replace(/\\(["\\$`])/g, '$1');
+  // A shell WORD is a contiguous run of quoted and/or unquoted segments with no
+  // whitespace between them, so a `\S+` token boundary is wrong: an env prefix
+  // whose value is quoted and contains spaces (e.g. `FOO='a b' claude-code-acp`)
+  // is a SINGLE word `FOO=a b`, but `\S+` would split it into `FOO='a` and `b'`,
+  // corrupting commandIndex so the real `*-acp` command token is never checked
+  // (and `--acp` wrongly appended). Glue adjacent segments into one word.
+  const tokens = commandLine.match(/(?:'(?:[^']|'\\'')*'|"(?:[^"\\]|\\.)*"|[^\s'"]+)+/g) || [];
+  // Strip shell quoting across ALL of a word's segments (a word may mix quoted
+  // and unquoted runs, e.g. `FOO='a b'`), yielding the logical value.
+  const unquote = (tok) => {
+    let out = '';
+    const seg = /'((?:[^']|'\\'')*)'|"((?:[^"\\]|\\.)*)"|([^\s'"]+)/g;
+    let m;
+    while ((m = seg.exec(tok)) !== null) {
+      if (m[1] !== undefined) out += m[1].replace(/'\\''/g, "'");
+      else if (m[2] !== undefined) out += m[2].replace(/\\(["\\$`])/g, '$1');
+      else out += m[3];
     }
-    const base = tok.replace(/^.*[\\/]/, ''); // basename, for path-form commands
+    return out;
+  };
+  // The `*-acp` adapter suffix identifies the COMMAND token, but the command is
+  // not always token 0: a shell command line may be prefixed with a contiguous
+  // run of env assignments (`NAME=value`, e.g. the `ACP=true` in
+  // `ACP=true claude-code-acp`). Skip that leading assignment prefix so the
+  // adapter check lands on the real command token. Only a *leading* run counts —
+  // once a real command token appears, later `FOO=bar` tokens are arguments.
+  let commandIndex = 0;
+  while (commandIndex < tokens.length &&
+         /^[A-Za-z_][A-Za-z0-9_]*=/.test(unquote(tokens[commandIndex]))) {
+    commandIndex++;
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    let tok = unquote(tokens[i]);
+    // Normalise a GNU-style `--opt=value` selector to its option-NAME part, so
+    // `--acp=true` / `--experimental-acp=true` are detected as ACP selectors and
+    // never doubled. Only the option NAME selects ACP — a `--model=foo-acp`
+    // VALUE must not trigger (its name `--model` doesn't end in `-acp`).
+    // Strip `=value` ONLY for switch tokens (those starting with `-`): a
+    // non-switch token that happens to contain `=` — a leading env assignment
+    // like `ACP=true copilot` or a bare value `acp=true` — must NOT be truncated
+    // to `acp` and mis-detected as an ACP selector (a false positive that would
+    // wrongly skip appending `--acp`).
+    const name = tok.startsWith('-') ? tok.replace(/=.*$/s, '') : tok;
+    const base = name.replace(/^.*[\\/]/, ''); // basename, for path-form commands
     if (/^-{0,2}acp$/i.test(base)) return commandLine;
-    if (i === 0 && /-acp$/i.test(base)) return commandLine;
+    // A switch that NAMES acp, e.g. qwen's hidden `--experimental-acp` (present
+    // in the shipped cli.js but not in `qwen --help`) — a long/short option
+    // whose flag name ends in `-acp`. Matched in ANY position, since it is an
+    // argument to the harness command (not the command token). A bare value that
+    // merely ends in `-acp` (e.g. `--model foo-acp`) does NOT start with `-`, so
+    // it is not a switch and still (correctly) triggers the append below.
+    if (/^--?[a-z0-9][a-z0-9-]*-acp$/i.test(name)) return commandLine;
+    if (i === commandIndex && /-acp$/i.test(base)) return commandLine;
   }
   return `${commandLine} --acp`;
 }
@@ -5383,7 +5447,12 @@ async function workAgent(req, flags) {
 
   // Structured command-line switches: the profile's persisted `--arg`s, extended
   // by any work-time `--arg` (appended). Lets an operator add switches (e.g.
-  // `--allow-all`) at dispatch time without re-hiring.
+  // `--allow-all`) at dispatch time without re-hiring. A value-less `--arg`
+  // (bare flag, boolean `true`) is malformed — reject it rather than drop it.
+  if (hasValuelessArg(flags?.arg)) {
+    logger.error('--arg requires a value (e.g. --arg "--allow-all").');
+    process.exit(1);
+  }
   const effectiveArgs = [...profile.args, ...normalizeArgList(flags?.arg)];
 
   const intFlag = (v, dflt) => {
@@ -6529,13 +6598,15 @@ function extractNameFlag(parts) {
 const MAX_ADD_INSTANCES = 64;
 
 /**
- * Parse the `--instances N` count for `supervisor add`. Accepts undefined/blank
- * (defaults to 1), and a whole number in `[1, MAX_ADD_INSTANCES]`. Rejects
- * non-integers, zero/negatives, and anything over the cap with a clear message.
- * When a flag is repeated the last occurrence wins (arrays are tolerated).
- * Returns `{ count }` on success or `{ error }` on rejection. Pure.
+ * Parse the `--instances N` count for `supervisor add` / `workforce add`
+ * (the caller passes its own `cmdLabel`, which appears in the over-cap error).
+ * Accepts undefined/blank (defaults to 1), and a whole number in
+ * `[1, MAX_ADD_INSTANCES]`. Rejects non-integers, zero/negatives, and anything
+ * over the cap with a clear message. When a flag is repeated the last
+ * occurrence wins (arrays are tolerated). Returns `{ count }` on success or
+ * `{ error }` on rejection. Pure.
  */
-function parseInstancesCount(raw) {
+function parseInstancesCount(raw, cmdLabel = 'supervisor add') {
   const v = Array.isArray(raw) ? raw[raw.length - 1] : raw;
   if (v === undefined || v === null || (typeof v === 'string' && v.trim() === '')) {
     return { count: 1 };
@@ -6544,7 +6615,16 @@ function parseInstancesCount(raw) {
   if (!/^\d+$/.test(s)) return { error: `Invalid --instances "${v}": use a whole number between 1 and ${MAX_ADD_INSTANCES}.` };
   const n = Number.parseInt(s, 10);
   if (n < 1) return { error: `Invalid --instances "${v}": use a whole number between 1 and ${MAX_ADD_INSTANCES}.` };
-  if (n > MAX_ADD_INSTANCES) return { error: `--instances ${n} exceeds the ${MAX_ADD_INSTANCES}-per-command cap; run "supervisor add" again to add more.` };
+  if (n > MAX_ADD_INSTANCES) {
+    // `supervisor add` accumulates workers, so exceeding the cap can be worked
+    // around by re-running the command. Workforce entries are updated in place,
+    // so the cap is a hard per-entry maximum — the rerun hint would mislead.
+    return {
+      error: cmdLabel === 'supervisor add'
+        ? `--instances ${n} exceeds the ${MAX_ADD_INSTANCES}-per-command cap; run "${cmdLabel}" again to add more.`
+        : `--instances ${n} exceeds the ${MAX_ADD_INSTANCES}-per-entry maximum.`,
+    };
+  }
   return { count: n };
 }
 
@@ -8039,6 +8119,969 @@ async function supervisorCommand(req, flags) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// workforce — declarative workforce manifests (issue #117). A manifest is a
+// named, user-curated document (`<stateHome>/workforce/<name>.json`) describing
+// a fleet of supervised workers you compose once (`workforce add`) and bring up
+// convergently with one command (`workforce start`). It is deliberately a
+// SEPARATE file per manifest — a portable artifact meant to be read, edited,
+// diffed and copied between machines — not a key in `config.json` (plugin
+// state). `workforce start` reconciles the running supervisor to the manifest
+// using deterministic `wf-<manifest>-<profile>-<index>` worker names, so a
+// second start with an unchanged manifest starts/stops/restarts nothing.
+// ---------------------------------------------------------------------------
+
+const WORKFORCE_MANIFEST_VERSION = 1;
+const DEFAULT_WORKFORCE_MANIFEST = 'default';
+
+/** The directory holding per-name workforce manifests. */
+function getWorkforceDir() {
+  return join(getStateHome(), 'workforce');
+}
+
+/** The manifest file for a given manifest name (`<stateHome>/workforce/<name>.json`). */
+function getWorkforceManifestFile(name) {
+  return join(getWorkforceDir(), `${name}.json`);
+}
+
+/**
+ * A manifest name is valid iff it is a non-empty string of `[A-Za-z0-9._-]`
+ * whose first character is alphanumeric (`[A-Za-z0-9]`; same charset and rule
+ * as a profile name). It rides in both a filename and the deterministic
+ * `wf-<name>-` worker-name prefix, so this charset keeps it safe on disk and as
+ * a broker/supervisor worker id. Pure.
+ */
+function isValidManifestName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name);
+}
+
+/** An empty v1 manifest with the given name. Pure. */
+function emptyWorkforceManifest(name) {
+  return { version: WORKFORCE_MANIFEST_VERSION, name: String(name), workers: [] };
+}
+
+// A workforce role name (a capability token): starts with a letter/digit, then
+// letters/digits/`. _ + -`. No `:` (that delimits rank↔role in the mapped job
+// type). Roles are lowercased to match `normalizeCapabilities`.
+const WORKFORCE_ROLE_RE = /^[a-z0-9][a-z0-9._+-]*$/i;
+
+/**
+ * Parse a `--roles a,b,c` value (string | string[]) into a deduped, validated,
+ * lowercased list of role names. Returns `{ roles, errors }`. Pure.
+ */
+function parseRolesList(raw) {
+  const fromArray = Array.isArray(raw);
+  const rawItems = fromArray ? raw : [raw];
+  const seen = new Set();
+  const roles = [];
+  const errors = [];
+  for (const rawItem of rawItems) {
+    if (typeof rawItem !== 'string') {
+      // Array elements must all be strings. For a lone scalar, a nullish value
+      // means "no roles supplied" (empty result, no error), but any other
+      // non-string (e.g. boolean `true` from a value-less `--roles` flag, or a
+      // torn JSON value) is a malformed value, not a role — reject it rather
+      // than coerce it into a phantom role like "true".
+      if (fromArray || rawItem != null) {
+        errors.push(`invalid role ${JSON.stringify(rawItem)} (expected a role-name string)`);
+      }
+      continue;
+    }
+    // A single value may itself be comma-separated (`--roles a,b`); repeated
+    // flags arrive as an array whose elements may also be comma-separated
+    // (`--roles a,b --roles c`), so split every element on commas.
+    for (const item of rawItem.split(',')) {
+      const r = item.trim().toLowerCase();
+      if (!r) continue;
+      if (!WORKFORCE_ROLE_RE.test(r)) { errors.push(`invalid role "${item.trim()}" (use letters, digits, and . _ + -)`); continue; }
+      if (seen.has(r)) continue;
+      seen.add(r);
+      roles.push(r);
+    }
+  }
+  return { roles, errors };
+}
+
+/**
+ * Map an explicit role list to repeatable `--job-type <rank>:<role>` tokens,
+ * resolved AT START TIME from the manifest and the hired profile's rank —
+ * independent of what the profile was hired with (the install script hires with
+ * `--capabilities ""`). `["pr-review"]` × rank `senior` → `["senior:pr-review"]`.
+ * Pure and unit-tested.
+ */
+function rolesToJobTypes(roles, rank) {
+  if (!Array.isArray(roles)) return [];
+  const r = String(rank || '').trim();
+  return roles.map((role) => `${r}:${String(role).trim()}`);
+}
+
+/**
+ * Translate one manifest entry (+ the resolved hired-profile rank) into the
+ * `nano work` argv tail a supervised worker runs with:
+ *   - `roles: "auto"` → `--auto [--auto-scope <s>]` (no capability gate; serves
+ *     every deployed agent job type — what the install script sets).
+ *   - `roles: [...]`  → repeatable `--job-type <rank>:<role>` per role.
+ * Then any verbatim `entry.args` escape-hatch flags are appended. Neither form
+ * mutates the hired profile. Pure and unit-tested.
+ */
+function manifestEntryToWorkArgs(entry, rank) {
+  const out = [];
+  const roles = entry?.roles;
+  if (roles === 'auto' || roles == null) {
+    out.push('--auto');
+    const scope = typeof entry?.autoScope === 'string' ? entry.autoScope.trim() : '';
+    if (scope) out.push('--auto-scope', scope);
+  } else if (Array.isArray(roles)) {
+    for (const jt of rolesToJobTypes(roles, rank)) out.push('--job-type', jt);
+  }
+  for (const a of normalizeArgList(entry?.args)) out.push(a);
+  return out;
+}
+
+/** The ownership prefix for a manifest's workforce-owned workers. Pure. */
+function workforceOwnerPrefix(manifest) {
+  return `wf-${manifest}-`;
+}
+
+/** The deterministic worker name for the Nth instance of a profile. Pure. */
+function workforceWorkerName(manifest, profile, index) {
+  return `${workforceOwnerPrefix(manifest)}${profile}-${index}`;
+}
+
+/**
+ * Is worker `id` owned by `manifest`? A worker name is
+ * `wf-<manifest>-<profile>-<index>`, and BOTH the manifest name and the profile
+ * may contain `-` (see `isValidManifestName`), so a bare `wf-<manifest>-` prefix
+ * test is ambiguous: manifest `a` would otherwise claim `wf-a-b-...` workers that
+ * actually belong to manifest `a-b`, letting `workforce start/stop/status`
+ * stop or report another manifest's workers. We disambiguate by LONGEST-prefix
+ * ownership against the manifest names that exist on this machine
+ * (`manifestNames`): `id` belongs to `manifest` only when no OTHER existing
+ * manifest name is a longer `wf-<name>-` prefix of `id`. When `manifestNames` is
+ * absent/empty this degrades to the plain prefix test (unchanged behaviour), so
+ * a worker whose more-specific owner no longer exists on disk stays claimable as
+ * an orphan under its prefix. Pure.
+ */
+function isWorkforceOwnedWorker(id, manifest, manifestNames) {
+  if (typeof id !== 'string' || !id.startsWith(workforceOwnerPrefix(manifest))) return false;
+  const names = Array.isArray(manifestNames) ? manifestNames : [];
+  for (const other of names) {
+    if (other === manifest) continue;
+    if (other.length > manifest.length && id.startsWith(workforceOwnerPrefix(other))) return false;
+  }
+  return true;
+}
+
+/**
+ * Parse the `<profile>` embedded in a deterministic
+ * `wf-<manifest>-<profile>-<index>` worker id, given the owning manifest.
+ * Returns the profile string, or `null` when `id` does not carry this manifest's
+ * `wf-<manifest>-` prefix or does not end in a `-<index>` counter (a hand-added
+ * id that merely shares the prefix). A profile name may itself contain dashes,
+ * so we peel the trailing `-<digits>` index and treat the remainder as the
+ * profile. Pure — mirrors `workforceWorkerName`'s construction.
+ */
+function workforceProfileFromWorkerName(manifest, id) {
+  const prefix = workforceOwnerPrefix(manifest);
+  if (typeof id !== 'string' || !id.startsWith(prefix)) return null;
+  const rest = id.slice(prefix.length);
+  const m = rest.match(/^(.+)-(\d+)$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Expand a manifest into the flat list of desired workers it describes:
+ * `[{ name, profile, index, entry }]`, one per instance. Pure.
+ */
+function expandWorkforceDesired(manifest) {
+  const name = manifest?.name;
+  const entries = Array.isArray(manifest?.workers) ? manifest.workers : [];
+  const out = [];
+  for (const entry of entries) {
+    const profile = entry?.profile;
+    const instances = Number(entry?.instances) || 0;
+    for (let i = 1; i <= instances; i++) {
+      out.push({ name: workforceWorkerName(name, profile, i), profile, index: i, entry });
+    }
+  }
+  return out;
+}
+
+/**
+ * The convergent reconcile diff for `workforce start`, factored as a PURE
+ * function over (desired workers, live supervisor workers, manifest name) so it
+ * is unit-testable directly (mirroring how `diffJobTypes` is factored):
+ *   - `toStart`   — desired workers not currently running (by exact name).
+ *   - `toStop`    — live workers OWNED by this manifest (the `wf-<manifest>-`
+ *                   name prefix) that are no longer desired (entry removed or
+ *                   `instances` reduced).
+ *   - `toRestart` — desired workers present in supervisor status under the same
+ *                   profile but NOT actually running (e.g. `state: "down"` while
+ *                   crashed / mid-backoff). Restarting them lets `workforce
+ *                   start` converge back to the desired *running* fleet instead
+ *                   of counting a down worker as "unchanged". A live worker with
+ *                   no `state` field (older status payloads) is assumed running.
+ *   - `unchanged` — desired workers already running under the same profile.
+ *   - `collisions`— a desired name is already taken by a worker running a
+ *                   DIFFERENT profile (a hand-added worker that clashes): it is
+ *                   neither started (don't clobber) nor stopped (not ours).
+ * Workers NOT owned by this manifest (added by hand with `supervisor add`, or
+ * owned by another manifest) are never in `toStop`. `desired` is
+ * `[{ name, profile, ... }]`; `live` is `[{ id, profile }]`.
+ *
+ * `skippedProfiles` names manifest entries whose profile could not be resolved
+ * this run (a local config error, e.g. a deleted hire). Such an entry produces
+ * NO desired workers, so its already-running `wf-<manifest>-<profile>-*` workers
+ * would otherwise be swept into `toStop` — turning a validation error into a
+ * destructive teardown. We PROTECT those workers instead: they are left running
+ * (reported under `protected`) so a config problem never tears down part of the
+ * live fleet. Pure.
+ */
+function reconcileWorkforce({ desired, live, manifest, skippedProfiles, manifestNames }) {
+  const liveList = Array.isArray(live) ? live : [];
+  const liveById = new Map();
+  for (const w of liveList) { if (w && typeof w.id === 'string') liveById.set(w.id, w); }
+  const desiredList = Array.isArray(desired) ? desired : [];
+  const desiredNames = new Set(desiredList.map((d) => d.name));
+  const protectedProfiles = new Set(Array.isArray(skippedProfiles) ? skippedProfiles : []);
+  // Compare the worker id's EMBEDDED profile exactly against skippedProfiles.
+  // A prefix `startsWith` check would over-match when profile names contain '-'
+  // (e.g. skipping "a" must not protect "a-b"'s `wf-<manifest>-a-b-*` workers).
+  const isProtected = (id) => protectedProfiles.has(workforceProfileFromWorkerName(manifest, id));
+  const toStart = [];
+  const toRestart = [];
+  const unchanged = [];
+  const collisions = [];
+  for (const d of desiredList) {
+    const existing = liveById.get(d.name);
+    if (!existing) { toStart.push(d); continue; }
+    if (existing.profile != null && d.profile != null && existing.profile !== d.profile) {
+      collisions.push({ name: d.name, wantProfile: d.profile, haveProfile: existing.profile });
+      continue;
+    }
+    // A worker known to the supervisor but NOT running (state present and not
+    // "running", e.g. "down" while crashed/mid-backoff) is restarted so `start`
+    // converges to the desired *running* fleet. Missing state ⇒ assume running.
+    if (existing.state != null && existing.state !== 'running') { toRestart.push(d); continue; }
+    unchanged.push(d);
+  }
+  const toStop = [];
+  const protectedWorkers = [];
+  for (const w of liveList) {
+    if (!w || typeof w.id !== 'string') continue;
+    if (!isWorkforceOwnedWorker(w.id, manifest, manifestNames) || desiredNames.has(w.id)) continue;
+    if (isProtected(w.id)) { protectedWorkers.push(w.id); continue; }
+    toStop.push(w.id);
+  }
+  return { toStart, toRestart, toStop, unchanged, collisions, protected: protectedWorkers };
+}
+
+/**
+ * Validate + normalize one stored manifest entry, returning `{ entry }` or
+ * `{ error }`. Enforces: a profile string, `instances` in `[1, MAX_ADD_INSTANCES]`,
+ * and `roles` being either `"auto"` (with an optional `autoScope`) or a
+ * non-empty array of valid role names. Pure — no config/hire I/O (the profile's
+ * EXISTENCE is checked at add/start against `hires`, not here). Pure.
+ */
+function normalizeManifestEntry(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return { error: 'entry is not an object' };
+  const profile = String(entry.profile || '').trim();
+  if (!profile) return { error: 'entry is missing a profile' };
+  // A manifest is hand-editable, so enforce the same safe charset as a hired
+  // profile name here: the profile rides into the deterministic
+  // `wf-<manifest>-<profile>-<index>` worker id, and a torn value like "bad
+  // name" would otherwise pass and fail later in a less obvious place.
+  if (!isValidProfileName(profile)) {
+    return { error: `entry "${profile}": invalid profile name (use letters, digits, dot, dash or underscore)` };
+  }
+  const { count, error } = parseInstancesCount(entry.instances, 'workforce add');
+  if (error) return { error: `entry "${profile}": ${error}` };
+  let roles;
+  let autoScope;
+  // Distinguish an ABSENT `roles` field (a legitimate "default to auto") from a
+  // field that is PRESENT but malformed — including an explicit `null`, which is
+  // a torn value, not "auto". Keying on presence (mirrors the strict `workers:
+  // null` rejection above) surfaces the corruption instead of silently
+  // broadening the worker to `--auto` serving.
+  const rolesAbsent = !('roles' in entry) || entry.roles === undefined;
+  if (entry.roles === 'auto' || rolesAbsent) {
+    roles = 'auto';
+    const scope = typeof entry.autoScope === 'string' ? entry.autoScope.trim() : '';
+    if (scope) autoScope = scope;
+  } else if (Array.isArray(entry.roles)) {
+    const { roles: rs, errors } = parseRolesList(entry.roles);
+    if (errors.length) return { error: `entry "${profile}": ${errors.join('; ')}` };
+    if (rs.length === 0) return { error: `entry "${profile}": roles array is empty` };
+    roles = rs;
+  } else {
+    return { error: `entry "${profile}": roles must be "auto" or an array of role names` };
+  }
+  // `args` is documented as an array of extra verbatim `work` flags. Like
+  // roles/workers above, distinguish an ABSENT `args` (legitimately "no extra
+  // flags") from one that is PRESENT but malformed. Left to normalizeArgList, a
+  // torn/hand-edited value such as { "args": [true] } (or an empty string) would
+  // be silently dropped/coerced, so the flag looks accepted when it was actually
+  // discarded — contradicting the "malformed manifests are refused" contract and
+  // making debugging hard. Reject non-string / empty values here, naming the
+  // entry, rather than normalize them away.
+  const argsAbsent = !('args' in entry) || entry.args === undefined;
+  let args = [];
+  if (!argsAbsent) {
+    if (!Array.isArray(entry.args)) {
+      return { error: `entry "${profile}": args must be an array of flag strings` };
+    }
+    for (const a of entry.args) {
+      if (typeof a !== 'string') {
+        return { error: `entry "${profile}": invalid arg ${JSON.stringify(a)} (expected a flag string)` };
+      }
+      if (a.length === 0) {
+        return { error: `entry "${profile}": args contains an empty string (expected a flag string)` };
+      }
+    }
+    args = normalizeArgList(entry.args);
+  }
+  const out = { profile, instances: count, roles };
+  if (autoScope) out.autoScope = autoScope;
+  if (args.length) out.args = args;
+  return { entry: out };
+}
+
+/**
+ * Validate a parsed manifest object against the v1 schema, THROWING a clear
+ * error naming the file path on any problem (mirroring `readConfigStrict()`'s
+ * "absent vs unreadable" distinction — a torn/unknown manifest is never silently
+ * treated as empty). Refuses an unknown `version` rather than best-effort
+ * parsing. Returns the normalized manifest.
+ */
+function validateWorkforceManifest(parsed, file, expectedName) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`workforce manifest ${file} is malformed (expected a JSON object).`);
+  }
+  if (parsed.version !== WORKFORCE_MANIFEST_VERSION) {
+    throw new Error(`workforce manifest ${file} has unsupported version ${JSON.stringify(parsed.version)} (this build understands version ${WORKFORCE_MANIFEST_VERSION}).`);
+  }
+  // Distinguish an ABSENT `workers` field (a legitimately empty manifest) from
+  // one that is PRESENT but not an array — including an explicit `null`, which
+  // is a malformed value, not "empty". `!= null` used to let `null` slip
+  // through as empty; keying on presence surfaces the corruption instead.
+  if ('workers' in parsed && parsed.workers !== undefined && !Array.isArray(parsed.workers)) {
+    throw new Error(`workforce manifest ${file} has a malformed "workers" field (expected an array, got ${parsed.workers === null ? 'null' : typeof parsed.workers}).`);
+  }
+  const workersRaw = Array.isArray(parsed.workers) ? parsed.workers : [];
+  const workers = [];
+  const seenProfiles = new Set();
+  for (const raw of workersRaw) {
+    const norm = normalizeManifestEntry(raw);
+    if (norm.error) throw new Error(`workforce manifest ${file}: ${norm.error}.`);
+    // Reject duplicate profiles: two entries for the same profile expand to the
+    // same deterministic `wf-<manifest>-<profile>-<index>` worker names, so
+    // `workforce start` would try `supervisor add` for the same worker id twice
+    // and fail non-deterministically. Surface the corruption here (naming the
+    // path) — use "instances" to run multiple copies of one profile.
+    if (seenProfiles.has(norm.entry.profile)) {
+      throw new Error(`workforce manifest ${file} has a duplicate profile ${JSON.stringify(norm.entry.profile)} — each profile may appear at most once (use "instances" to run more than one).`);
+    }
+    seenProfiles.add(norm.entry.profile);
+    workers.push(norm.entry);
+  }
+  const onDiskName = typeof parsed.name === 'string' && parsed.name.trim() ? parsed.name.trim() : '';
+  // When loaded by name, the file's identity (its path) is authoritative: a
+  // hand-edited `name` that disagrees would make writeWorkforceManifest() target
+  // a *different* file, silently corrupting an unrelated manifest. Refuse it
+  // rather than trust the field (mirrors the strict "surface corruption" ethos).
+  const expected = String(expectedName || '').trim();
+  if (expected && onDiskName && onDiskName !== expected) {
+    throw new Error(`workforce manifest ${file} declares name ${JSON.stringify(onDiskName)} but was loaded as ${JSON.stringify(expected)} — the manifest name must match its filename.`);
+  }
+  const name = onDiskName || expected;
+  return { version: WORKFORCE_MANIFEST_VERSION, name, workers };
+}
+
+/**
+ * Read + validate a manifest by name. Returns the normalized manifest, or
+ * `null` when the file is absent. THROWS (naming the path) on an unreadable
+ * file, torn/non-JSON content, or a schema/version violation — so callers never
+ * mistake "unreadable" for "empty".
+ */
+function readWorkforceManifestStrict(name) {
+  const file = getWorkforceManifestFile(name);
+  if (!existsSync(file)) return null;
+  let raw;
+  try { raw = readFileSync(file, 'utf-8'); }
+  catch (err) { throw new Error(`could not read workforce manifest ${file}: ${err.message}`); }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) { throw new Error(`workforce manifest ${file} is not valid JSON: ${err.message}`); }
+  return validateWorkforceManifest(parsed, file, name);
+}
+
+/** Atomically persist a manifest to `<stateHome>/workforce/<name>.json`. */
+function writeWorkforceManifest(manifest) {
+  mkdirSync(getWorkforceDir(), { recursive: true });
+  const target = getWorkforceManifestFile(manifest.name);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  // Owner-only (0600): manifests record forwarded `work` flags via `args`
+  // (e.g. `--env NAME=VALUE`), so keep them out of world-readable view on
+  // multi-user machines, consistent with supervisor.json.
+  writeFileSync(tmp, JSON.stringify(manifest, null, 2), { mode: 0o600 });
+  try { renameSync(tmp, target); }
+  catch (err) { try { rmSync(tmp, { force: true }); } catch { /* best effort */ } throw err; }
+}
+
+/** All manifest names that exist on disk (sorted). Best-effort IO. */
+function listWorkforceManifestNames() {
+  let entries;
+  try { entries = readdirSync(getWorkforceDir()); }
+  catch { return []; }
+  return entries
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.slice(0, -'.json'.length))
+    .filter((n) => n && isValidManifestName(n))
+    .sort();
+}
+
+/**
+ * Append or update-in-place a manifest entry, matched by `profile` (idempotent,
+ * matching `hire`'s update-in-place semantics). Returns a new manifest. Pure.
+ */
+function upsertManifestEntry(manifest, entry) {
+  const workers = Array.isArray(manifest.workers) ? manifest.workers.slice() : [];
+  const idx = workers.findIndex((w) => w && w.profile === entry.profile);
+  if (idx >= 0) workers[idx] = entry; else workers.push(entry);
+  return { ...manifest, workers };
+}
+
+/**
+ * Drop a manifest entry by profile, or clear ALL entries when `profile` is
+ * `"all"`. Returns `{ manifest, removed }` where `removed` lists the dropped
+ * profiles. Pure.
+ */
+function removeManifestEntry(manifest, profile) {
+  const workers = Array.isArray(manifest.workers) ? manifest.workers : [];
+  if (profile === 'all') {
+    return { manifest: { ...manifest, workers: [] }, removed: workers.map((w) => w && w.profile).filter(Boolean) };
+  }
+  const kept = [];
+  let removed = null;
+  for (const w of workers) {
+    if (w && w.profile === profile) removed = w.profile;
+    else kept.push(w);
+  }
+  return { manifest: { ...manifest, workers: kept }, removed: removed ? [removed] : [] };
+}
+
+/** Human-readable one-line summary of an entry's roles. Pure. */
+function describeEntryRoles(entry) {
+  if (Array.isArray(entry?.roles)) return entry.roles.join(', ');
+  const scope = typeof entry?.autoScope === 'string' && entry.autoScope ? ` (scope ${entry.autoScope})` : '';
+  return `auto${scope}`;
+}
+
+/** Render a manifest as an aligned text table for `workforce list`. Pure. */
+function formatWorkforceManifest(manifest) {
+  const lines = [];
+  lines.push(`Workforce "${manifest.name}" (v${manifest.version ?? WORKFORCE_MANIFEST_VERSION}):`);
+  const entries = Array.isArray(manifest.workers) ? manifest.workers : [];
+  if (entries.length === 0) {
+    lines.push('  (empty — add workers with: c8ctl nano workforce add <profile> --instances N [--auto|--roles a,b])');
+    return lines.join('\n');
+  }
+  const rows = entries.map((e) => ({
+    profile: String(e.profile),
+    instances: String(e.instances ?? 1),
+    roles: describeEntryRoles(e),
+    args: Array.isArray(e.args) && e.args.length ? e.args.join(' ') : '-',
+  }));
+  const head = { profile: 'PROFILE', instances: 'INSTANCES', roles: 'ROLES', args: 'ARGS' };
+  const cols = ['profile', 'instances', 'roles', 'args'];
+  const width = {};
+  for (const c of cols) width[c] = Math.max(head[c].length, ...rows.map((r) => r[c].length));
+  const fmt = (r) => '  ' + cols.map((c) => r[c].padEnd(width[c])).join('  ');
+  lines.push(fmt(head));
+  for (const r of rows) lines.push(fmt(r));
+  return lines.join('\n');
+}
+
+/**
+ * Build the `workforce status` report — the manifest's entries joined against
+ * the live supervisor worker set — as a plain data object (also the `--json`
+ * shape). For each entry it reports desired vs actual instance counts and the
+ * per-instance worker (present/state/pid/uptime/restarts); plus `extra` workers
+ * owned by this manifest (the `wf-<name>-` prefix) that no entry desires. Pure
+ * over its inputs. `live` is an array of summarized supervisor workers.
+ */
+function buildWorkforceStatus(manifest, name, live, supervisorRunning, manifestNames) {
+  const liveList = Array.isArray(live) ? live : [];
+  const liveById = new Map();
+  for (const w of liveList) { if (w && typeof w.id === 'string') liveById.set(w.id, w); }
+  const entriesRaw = Array.isArray(manifest?.workers) ? manifest.workers : [];
+  const desiredNames = new Set();
+  const entries = entriesRaw.map((e) => {
+    const workers = [];
+    let running = 0;
+    for (let i = 1; i <= (Number(e.instances) || 0); i++) {
+      const wname = workforceWorkerName(name, e.profile, i);
+      desiredNames.add(wname);
+      const w = liveById.get(wname) || null;
+      // Mirror reconcile's collision rule: a live worker occupying the desired
+      // NAME but running a DIFFERENT profile does NOT satisfy this instance
+      // (workforce start skips such a name collision rather than clobbering it).
+      // Treat it as a collision — the desired instance is effectively absent —
+      // and surface the intruding profile so status doesn't mask the clash by
+      // reporting the instance as "running".
+      const collision = w && w.profile != null && e.profile != null && String(w.profile) !== String(e.profile)
+        ? String(w.profile)
+        : null;
+      const eff = collision ? null : w;
+      // Mirror reconcile: a live worker with no `state` (older supervisor
+      // status payloads) is assumed running, not "undefined".
+      const state = eff ? (eff.state != null ? String(eff.state) : 'running') : 'absent';
+      if (state === 'running') running++;
+      workers.push({
+        name: wname,
+        present: Boolean(eff),
+        state,
+        pid: eff && eff.pid != null ? eff.pid : null,
+        uptimeMs: eff && Number.isFinite(eff.uptimeMs) ? eff.uptimeMs : null,
+        restarts: eff ? Number(eff.restarts) || 0 : 0,
+        collision,
+      });
+    }
+    return {
+      profile: e.profile,
+      roles: e.roles,
+      autoScope: e.autoScope ?? null,
+      desired: Number(e.instances) || 0,
+      running,
+      workers,
+    };
+  });
+  const extra = liveList
+    .filter((w) => w && typeof w.id === 'string' && isWorkforceOwnedWorker(w.id, name, manifestNames) && !desiredNames.has(w.id))
+    .map((w) => ({ name: w.id, profile: w.profile ?? null, state: w.state != null ? String(w.state) : 'running', pid: w.pid ?? null }));
+  return {
+    name,
+    exists: Boolean(manifest),
+    supervisorRunning: Boolean(supervisorRunning),
+    entries,
+    extra,
+  };
+}
+
+/** Render a `buildWorkforceStatus` report as an aligned text table. Pure. */
+function formatWorkforceStatus(report) {
+  const lines = [];
+  lines.push(`Workforce "${report.name}":`);
+  if (!report.exists) {
+    lines.push('  (no manifest — create one with: c8ctl nano workforce add <profile> ...)');
+    return lines.join('\n');
+  }
+  lines.push(`  supervisor: ${report.supervisorRunning ? 'running' : 'not running'}`);
+  const entries = Array.isArray(report.entries) ? report.entries : [];
+  if (entries.length === 0) {
+    lines.push('  (empty manifest)');
+    return lines.join('\n');
+  }
+  const rows = [];
+  for (const e of entries) {
+    for (const w of e.workers) {
+      rows.push({
+        worker: w.name,
+        profile: String(e.profile),
+        desired: `${e.running}/${e.desired}`,
+        state: w.collision ? `collision(${w.collision})` : w.state,
+        pid: w.pid ? String(w.pid) : '-',
+        restarts: String(w.restarts),
+        uptime: w.state === 'running' && w.uptimeMs != null ? formatDuration(w.uptimeMs) : '-',
+      });
+    }
+  }
+  if (rows.length > 0) {
+    const head = { worker: 'WORKER', profile: 'PROFILE', desired: 'RUN/WANT', state: 'STATE', pid: 'PID', restarts: 'RESTARTS', uptime: 'UPTIME' };
+    const cols = ['worker', 'profile', 'desired', 'state', 'pid', 'restarts', 'uptime'];
+    const width = {};
+    for (const c of cols) width[c] = Math.max(head[c].length, ...rows.map((r) => r[c].length));
+    const fmt = (r) => '  ' + cols.map((c) => r[c].padEnd(width[c])).join('  ');
+    lines.push('');
+    lines.push(fmt(head));
+    for (const r of rows) lines.push(fmt(r));
+  }
+  const missing = entries.filter((e) => e.running < e.desired);
+  if (missing.length > 0) {
+    lines.push('');
+    lines.push(`  Missing: ${missing.map((e) => `${e.profile} (${e.running}/${e.desired})`).join(', ')} — run: c8ctl nano workforce start${report.name === DEFAULT_WORKFORCE_MANIFEST ? '' : ` --profile ${report.name}`}`);
+  }
+  if (Array.isArray(report.extra) && report.extra.length > 0) {
+    lines.push('');
+    lines.push(`  Extra (owned by this workforce, not desired): ${report.extra.map((w) => w.name).join(', ')} — will be stopped on next start.`);
+  }
+  return lines.join('\n');
+}
+
+/** Resolve the manifest name from `--profile` (default `default`). Pure. */
+function lastProfileValue(flags) {
+  // A repeated `--profile` flag arrives as a string[]; honor the last value.
+  let profile = flags?.profile;
+  if (Array.isArray(profile)) profile = profile.length ? profile[profile.length - 1] : '';
+  return typeof profile === 'string' ? profile.trim() : '';
+}
+
+function workforceManifestName(flags) {
+  return lastProfileValue(flags) || DEFAULT_WORKFORCE_MANIFEST;
+}
+
+/** Fetch the live supervisor worker set, or `[]` when no daemon is running. */
+async function fetchSupervisorWorkers() {
+  const running = await liveSupervisor();
+  if (!running) return { running: false, reachable: false, workers: [] };
+  try {
+    const res = await supervisorRequest({ op: 'status' });
+    if (res && res.ok) return { running: true, reachable: true, workers: Array.isArray(res.workers) ? res.workers : [] };
+  } catch { /* socket unreachable */ }
+  return { running: true, reachable: false, workers: [] };
+}
+
+async function workforceAddCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const profile = req.positional[1];
+  if (!profile) {
+    logger.error('Usage: c8ctl nano workforce add <profile> [--instances <n>] [--auto [--auto-scope <s>] | --roles a,b,c] [--arg <flag> ...] [--profile <manifest>]');
+    process.exit(1);
+  }
+  if (!isValidProfileName(profile)) {
+    logger.error(`Invalid profile name "${profile}". Use letters, digits, dot, dash or underscore.`);
+    process.exit(1);
+  }
+  // The profile must be a hired profile — validated here at `add` and again at
+  // `start`. readHiresStrict throws on a torn config (surfaced by the handler).
+  const hires = readHiresStrict();
+  if (!hires[profile]) {
+    logger.error(`No hired profile "${profile}". Create one first with: c8ctl nano hire --name ${profile} --rank <r> --command <cmd>`);
+    process.exit(1);
+  }
+  const { count, error } = parseInstancesCount(flags?.instances, 'workforce add');
+  if (error) { logger.error(error); process.exit(1); }
+  const auto = coerceBool(flags?.auto, false);
+  const rolesFlag = flags?.roles;
+  // A bare `--roles` (no value) is parsed as boolean `true` by the flag layer;
+  // reject it rather than let `String(true)` create a phantom role named "true"
+  // (mirrors how `--instances` rejects a non-numeric value).
+  if (rolesFlag === true) {
+    logger.error('--roles requires a comma-separated list of role names (e.g. --roles pr-review,fix).');
+    process.exit(1);
+  }
+  // An explicitly provided but empty `--roles` (e.g. `--roles ""`, or an empty
+  // array from the flag layer) is a user error, not an implicit "auto": reject
+  // it rather than silently defaulting the entry to `roles: "auto"`.
+  if (rolesFlag != null && String(rolesFlag).trim() === '') {
+    logger.error('--roles requires a comma-separated list of role names (e.g. --roles pr-review,fix).');
+    process.exit(1);
+  }
+  const hasRoles = rolesFlag != null;
+  if (flags?.['auto-scope'] === true) {
+    logger.error('--auto-scope requires a value.');
+    process.exit(1);
+  }
+  const autoScope = flags?.['auto-scope'] != null ? String(flags['auto-scope']).trim() : '';
+  if (auto && hasRoles) {
+    logger.error('--auto and --roles are mutually exclusive: an entry is either "auto" (serve all deployed job types) or an explicit role list.');
+    process.exit(1);
+  }
+  if (autoScope && !auto) {
+    logger.error('--auto-scope requires --auto.');
+    process.exit(1);
+  }
+  let entry;
+  if (hasRoles) {
+    const { roles, errors } = parseRolesList(rolesFlag);
+    if (errors.length) { logger.error(errors.join('; ')); process.exit(1); }
+    if (roles.length === 0) { logger.error('--roles must name at least one role.'); process.exit(1); }
+    entry = { profile, instances: count, roles };
+  } else {
+    // Neither --auto nor --roles → default to "auto" (serve every deployed agent
+    // job type), the onboarding/install-script happy path.
+    entry = { profile, instances: count, roles: 'auto' };
+    if (autoScope) entry.autoScope = autoScope;
+  }
+  // A value-less `--arg` (a bare flag with no following value) arrives as
+  // boolean `true` from the flag layer; normalizeArgList would silently drop it,
+  // making a malformed invocation look like it accepted the intended arg. Reject
+  // it up front (mirrors the `--roles`/`--auto-scope` value-less validation).
+  if (hasValuelessArg(flags?.arg)) {
+    logger.error('--arg requires a value (e.g. --arg "--allow-all-tools").');
+    process.exit(1);
+  }
+  const extraArgs = normalizeArgList(flags?.arg);
+  if (extraArgs.length) entry.args = extraArgs;
+
+  let manifest = readWorkforceManifestStrict(manifestName) || emptyWorkforceManifest(manifestName);
+  const existed = (manifest.workers || []).some((w) => w && w.profile === profile);
+  manifest = upsertManifestEntry(manifest, entry);
+  writeWorkforceManifest(manifest);
+  logger.info(`${existed ? 'Updated' : 'Added'} "${profile}" in workforce "${manifestName}": instances ${count}, roles ${describeEntryRoles(entry)}${extraArgs.length ? `, args ${redactWorkArgs(extraArgs).join(' ')}` : ''}.`);
+  logger.info(`Bring it up with: c8ctl nano workforce start${manifestName === DEFAULT_WORKFORCE_MANIFEST ? '' : ` --profile ${manifestName}`}`);
+}
+
+async function workforceRemoveCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const profile = req.positional[1];
+  if (!profile) {
+    logger.error('Usage: c8ctl nano workforce remove <profile|all> [--profile <manifest>]');
+    process.exit(1);
+  }
+  const manifest = readWorkforceManifestStrict(manifestName);
+  if (!manifest) { logger.warn(`Workforce "${manifestName}" does not exist — nothing to remove.`); return; }
+  const { manifest: next, removed } = removeManifestEntry(manifest, profile);
+  if (removed.length === 0) { logger.warn(`No entry for "${profile}" in workforce "${manifestName}".`); return; }
+  writeWorkforceManifest(next);
+  if (profile === 'all') logger.info(`Cleared workforce "${manifestName}" (${removed.length} entr${removed.length === 1 ? 'y' : 'ies'} removed).`);
+  else logger.info(`Removed "${profile}" from workforce "${manifestName}".`);
+}
+
+async function workforceListCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const json = coerceBool(flags?.json, false);
+  const explicitProfile = lastProfileValue(flags) !== '';
+  const manifest = readWorkforceManifestStrict(manifestName);
+  const others = explicitProfile ? null : listWorkforceManifestNames();
+  if (json) {
+    const payload = { manifest: manifest || null };
+    if (others) payload.manifests = others;
+    logger.output(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (!manifest) {
+    logger.info(`Workforce "${manifestName}" does not exist. Create it with: c8ctl nano workforce add <profile> --instances N [--auto|--roles a,b]`);
+  } else {
+    logger.output(formatWorkforceManifest(manifest));
+  }
+  if (others && others.length > 0) {
+    logger.info('');
+    logger.info(`Manifests on this machine: ${others.join(', ')}`);
+  }
+}
+
+async function workforceStartCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const manifest = readWorkforceManifestStrict(manifestName);
+  if (!manifest || !Array.isArray(manifest.workers) || manifest.workers.length === 0) {
+    logger.info(`Workforce "${manifestName}" is empty — nothing to start. Add workers with: c8ctl nano workforce add <profile> --instances N [--auto|--roles a,b]`);
+    return; // friendly, exit 0
+  }
+  // Resolve each entry's profile → rank and its work args. A profile deleted
+  // since it was added yields a clear error, is skipped, and forces a non-zero
+  // exit at the end — a partial start never leaves a half-reconciled fleet
+  // silently.
+  const hires = readHiresStrict();
+  const desired = [];
+  const skippedProfiles = [];
+  let hadError = false;
+  for (const entry of manifest.workers) {
+    const stored = hires[entry.profile];
+    if (!stored) {
+      logger.error(`Skipping "${entry.profile}": no such hired profile (create it with c8ctl nano hire --name ${entry.profile} ...).`);
+      skippedProfiles.push(entry.profile);
+      hadError = true;
+      continue;
+    }
+    const norm = normalizeStoredProfile(entry.profile, stored);
+    if (norm.error) {
+      logger.error(`Skipping "${entry.profile}": ${norm.error}.`);
+      skippedProfiles.push(entry.profile);
+      hadError = true;
+      continue;
+    }
+    const args = manifestEntryToWorkArgs(entry, norm.profile.rank);
+    for (let i = 1; i <= entry.instances; i++) {
+      desired.push({ name: workforceWorkerName(manifestName, entry.profile, i), profile: entry.profile, args });
+    }
+  }
+
+  // If every manifest entry was skipped (missing/invalid profiles), `desired` is
+  // empty and there is nothing to reconcile. Starting the supervisor daemon here
+  // would spin up (and leave behind) an empty daemon purely as a side effect of
+  // an all-error run. Report the failure, render current status without starting
+  // anything, and exit non-zero.
+  if (desired.length === 0) {
+    logger.error(`Workforce "${manifestName}": every entry was skipped (${skippedProfiles.join(', ')}) — nothing to start. Not starting a supervisor daemon.`);
+    await workforceStatusCmd(req, { ...flags, json: false }, manifestName);
+    process.exit(1);
+  }
+
+  const state = await startSupervisorDaemon();
+  logger.info(`Supervisor daemon running (pid ${state.pid}).`);
+  const { reachable, workers: live } = await fetchSupervisorWorkers();
+  // A running daemon with an unreachable status socket reports `live: []`, which
+  // would make reconcile think the fleet is empty — duplicating workers it can't
+  // see or "stopping" surplus it can't enumerate. Refuse to reconcile blindly
+  // and exit non-zero (mirrors `workforce stop`).
+  if (!reachable) {
+    logger.error('Supervisor daemon is running but its status socket is unreachable — cannot enumerate live workers to reconcile against. Refusing to reconcile blindly; try again once the socket responds.');
+    process.exit(1);
+  }
+  const { toStart, toRestart, toStop, unchanged, collisions, protected: protectedWorkers } = reconcileWorkforce({ desired, live, manifest: manifestName, skippedProfiles, manifestNames: listWorkforceManifestNames() });
+
+  for (const c of collisions) {
+    logger.warn(`Skipping "${c.name}": a worker with that name already runs profile "${c.haveProfile}" (manifest wants "${c.wantProfile}") — not clobbering a hand-added worker.`);
+    hadError = true;
+  }
+  for (const id of protectedWorkers) {
+    logger.warn(`  = kept "${id}" running (its profile could not be resolved this run — not tearing it down over a config error).`);
+  }
+  for (const id of toStop) {
+    const res = await supervisorRequest({ op: 'remove', target: id });
+    if (res && res.ok) logger.info(`  - stopped "${id}" (no longer desired)`);
+    else { logger.error(`  ! could not stop "${id}": ${(res && res.error) || 'unknown error'}`); hadError = true; }
+  }
+  for (const d of toStart) {
+    const res = await supervisorRequest({ op: 'add', profile: d.profile, name: d.name, args: d.args });
+    if (res && res.ok) logger.info(`  + started "${d.name}" (profile ${d.profile})`);
+    else { logger.error(`  ! could not start "${d.name}": ${(res && res.error) || 'unknown error'}`); hadError = true; }
+  }
+  for (const d of toRestart) {
+    const res = await supervisorRequest({ op: 'restart', target: d.name });
+    if (res && res.ok) logger.info(`  ↻ restarted "${d.name}" (was not running)`);
+    else { logger.error(`  ! could not restart "${d.name}": ${(res && res.error) || 'unknown error'}`); hadError = true; }
+  }
+  logger.info(`Workforce "${manifestName}" reconciled: ${toStart.length} started, ${toRestart.length} restarted, ${toStop.length} stopped, ${unchanged.length} unchanged${protectedWorkers.length ? `, ${protectedWorkers.length} kept (profile unresolved)` : ''}.`);
+
+  // `--json` is documented for `workforce list/status` only; forcing it off here
+  // keeps `workforce start --json` from appending a stray JSON blob to start's
+  // human-readable log (which would be neither pure text nor machine-readable).
+  await workforceStatusCmd(req, { ...flags, json: false }, manifestName);
+  if (hadError) process.exit(1);
+}
+
+async function workforceStatusCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const json = coerceBool(flags?.json, false);
+  const manifest = readWorkforceManifestStrict(manifestName);
+  const { running, reachable, workers: live } = await fetchSupervisorWorkers();
+  // When the daemon is up but its status socket can't be reached, `live` is
+  // empty and the report would falsely show every worker as absent — misleading
+  // a human and any automation consuming `--json`. Fail non-zero instead of
+  // rendering a phantom "everything down" status (mirrors `workforce stop`).
+  if (running && !reachable) {
+    logger.error('Supervisor is running but its status socket is unreachable — cannot report worker status. Try again once the socket responds.');
+    process.exit(1);
+  }
+  const report = buildWorkforceStatus(manifest, manifestName, live, running, listWorkforceManifestNames());
+  if (json) { logger.output(JSON.stringify(report, null, 2)); return; }
+  logger.output(formatWorkforceStatus(report));
+}
+
+async function workforceStopCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const running = await liveSupervisor();
+  if (!running) { logger.warn('Supervisor is not running — nothing to stop.'); return; }
+  const manifestNames = listWorkforceManifestNames();
+  const { running: stillRunning, reachable, workers: live } = await fetchSupervisorWorkers();
+  // The daemon can exit between the liveSupervisor() check above and this call;
+  // fetchSupervisorWorkers() then reports running:false (not merely
+  // unreachable). Treat that as "nothing to stop" rather than erroring out with
+  // a misleading "socket unreachable" message.
+  if (!stillRunning) { logger.warn('Supervisor is not running — nothing to stop.'); return; }
+  if (!reachable) {
+    logger.error('Supervisor is running but its status socket is unreachable — cannot enumerate workers. Leaving the daemon and its workers untouched.');
+    process.exit(1);
+  }
+  const owned = live
+    // Ownership is decided by longest-prefix match against the manifests that
+    // exist on this machine, so manifest `a` never claims manifest `a-b`'s
+    // `wf-a-b-...` workers even though its `wf-a-` prefix technically matches.
+    .filter((w) => w && typeof w.id === 'string' && isWorkforceOwnedWorker(w.id, manifestName, manifestNames))
+    // A worker id that carries our prefix but whose LIVE profile disagrees with
+    // the profile embedded in its deterministic name is a hand-added worker that
+    // merely collides on the name (the same case `workforce start` skips): it is
+    // NOT ours, so never remove it. Skip only on a positive disagreement — an
+    // id we can't parse a profile from, or a live worker with no reported
+    // profile, stays owned (unchanged from prior behaviour).
+    .filter((w) => {
+      const embedded = workforceProfileFromWorkerName(manifestName, w.id);
+      if (embedded != null && w.profile != null && w.profile !== embedded) {
+        logger.info(`Skipping "${w.id}" — it runs profile "${w.profile}", not the "${embedded}" this manifest owns (name collision); not removing.`);
+        return false;
+      }
+      return true;
+    })
+    .map((w) => w.id);
+  let hadError = false;
+  if (owned.length === 0) {
+    logger.info(`No workers from workforce "${manifestName}" are running.`);
+  } else {
+    for (const id of owned) {
+      const res = await supervisorRequest({ op: 'remove', target: id });
+      if (res && res.ok) logger.info(`Removed worker "${id}".`);
+      else { logger.error(`Could not remove "${id}": ${(res && res.error) || 'unknown error'}`); hadError = true; }
+    }
+  }
+  // If no supervised workers remain, stop the daemon too — but only when the
+  // status socket actually answered. A `{ workers: [] }` from an *unreachable*
+  // socket is ambiguous, and treating it as "empty" would wrongly kill the
+  // daemon (and any foreign workers it still supervises).
+  const { running: daemonStillRunning, reachable: stillReachable, workers: remaining } = await fetchSupervisorWorkers();
+  if (!daemonStillRunning) {
+    // The daemon exited/crashed between the removals and this re-check (its pid
+    // is no longer live), so there is nothing left to stop and reporting an
+    // unreachable *socket* would misdescribe a dead daemon as merely unanswered.
+    logger.warn('Supervisor daemon is no longer running.');
+  } else if (!stillReachable) {
+    logger.warn('Supervisor status socket became unreachable; leaving the daemon running.');
+  } else if (remaining.length === 0) {
+    logger.info('No supervised workers remain — stopping the supervisor daemon.');
+    await supervisorStopCmd();
+  } else {
+    logger.info(`${remaining.length} other supervised worker(s) remain; leaving the daemon running.`);
+  }
+  // A worker that could not be removed means the workforce is NOT fully stopped:
+  // exit non-zero so automation doesn't mistake a partial stop for success
+  // (consistent with `supervisor remove`, which also exits non-zero on failure).
+  if (hadError) process.exit(1);
+}
+
+async function workforceCommand(req, flags) {
+  const logger = getLogger();
+  const action = (req.positional[0] || '').toLowerCase();
+  // A bare `--profile` (no value) is parsed as boolean `true`; reject it so we
+  // fail fast instead of silently operating on the default manifest.
+  if (flags?.profile === true) {
+    logger.error('--profile requires a manifest name.');
+    process.exit(1);
+  }
+  const manifestName = workforceManifestName(flags);
+  if (!isValidManifestName(manifestName)) {
+    logger.error(`Invalid --profile "${manifestName}". Use letters, digits, dot, dash or underscore.`);
+    process.exit(1);
+  }
+  switch (action) {
+    case 'add':
+      await workforceAddCmd(req, flags, manifestName);
+      return;
+    case 'remove':
+    case 'rm':
+      await workforceRemoveCmd(req, flags, manifestName);
+      return;
+    case 'list':
+    case 'ls':
+      await workforceListCmd(req, flags, manifestName);
+      return;
+    case 'start':
+    case 'up':
+      await workforceStartCmd(req, flags, manifestName);
+      return;
+    case 'status':
+      await workforceStatusCmd(req, flags, manifestName);
+      return;
+    case 'stop':
+    case 'down':
+      await workforceStopCmd(req, flags, manifestName);
+      return;
+    default:
+      logger.error(`Unknown workforce action "${action}". Use: add|remove|list|start|status|stop`);
+      process.exit(1);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // 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
@@ -9742,6 +10785,7 @@ export {
   parseEnvPairs,
   normalizeEnvMap,
   normalizeArgList,
+  hasValuelessArg,
   shQuote,
   buildAgentCommandLine,
   reapAgentContainers,
@@ -9831,6 +10875,37 @@ export {
   getSupervisorStateFile,
 };
 
+export {
+  WORKFORCE_MANIFEST_VERSION,
+  DEFAULT_WORKFORCE_MANIFEST,
+  isValidManifestName,
+  emptyWorkforceManifest,
+  parseRolesList,
+  rolesToJobTypes,
+  manifestEntryToWorkArgs,
+  workforceOwnerPrefix,
+  workforceWorkerName,
+  workforceProfileFromWorkerName,
+  isWorkforceOwnedWorker,
+  expandWorkforceDesired,
+  reconcileWorkforce,
+  normalizeManifestEntry,
+  validateWorkforceManifest,
+  readWorkforceManifestStrict,
+  writeWorkforceManifest,
+  listWorkforceManifestNames,
+  getWorkforceDir,
+  getWorkforceManifestFile,
+  upsertManifestEntry,
+  removeManifestEntry,
+  describeEntryRoles,
+  formatWorkforceManifest,
+  buildWorkforceStatus,
+  formatWorkforceStatus,
+  workforceManifestName,
+  lastProfileValue,
+};
+
 export const metadata = {
   name: 'c8ctl-plugin-nano',
   description: 'Start, inspect, and stop a local Nano BPM (nanobpmn) cluster',
@@ -9883,6 +10958,13 @@ export const metadata = {
         { command: 'c8ctl nano supervisor add reviewer --instances 3', description: 'Add 3 distinct auto-named instances of a profile in one call' },
         { command: 'c8ctl nano supervisor restart reviewer', description: 'Restart a supervised worker by id or profile' },
         { command: 'c8ctl nano supervisor stop', description: 'Stop the supervisor daemon and all its workers' },
+        { command: 'c8ctl nano workforce add copilot --instances 5 --auto', description: 'Compose a reusable fleet: 5 copilot workers serving every deployed agent job type (--auto)' },
+        { command: 'c8ctl nano workforce add qwen --instances 2 --roles pr-review,feature', description: "Add an entry mapped to explicit job types (<rank>:pr-review, <rank>:feature, where <rank> is the qwen hire's rank at start) — does not mutate the hired profile" },
+        { command: 'c8ctl nano workforce start', description: "Ensure the daemon is up, then reconcile running workers to the 'default' manifest (idempotent — a second run changes nothing)" },
+        { command: 'c8ctl nano workforce start --profile review-only', description: 'Bring up a named manifest (<stateHome>/workforce/review-only.json)' },
+        { command: 'c8ctl nano workforce status --json', description: 'Manifest entries joined against live supervisor status (desired vs actual), machine-readable for the install script / CI' },
+        { command: 'c8ctl nano workforce list', description: 'Print the default manifest and list the manifests that exist on this machine' },
+        { command: 'c8ctl nano workforce stop', description: "Remove this manifest's workers; stop the daemon too if no supervised workers remain" },
       ],
     },
     processos: {
@@ -9926,7 +11008,7 @@ export const commands = {
       name: { type: 'string', description: 'work/supervisor add: worker name (auto ‹host›-‹profile›-‹random› if omitted); hire/assign: agent profile name' },
       rank: { type: 'string', description: 'hire: agent rank (principal|senior|junior|decider)' },
       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.' },
+      arg: { type: 'string', multiple: true, description: 'hire/work/workforce add: command-line switch/arg appended to the harness command (repeatable), e.g. --arg --allow-all. Persisted on hire; work appends more; workforce add sets the entry args.' },
       model: { type: 'string', description: 'hire: model name passed to the harness (AGENT_MODEL)' },
       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.' },
@@ -9949,11 +11031,14 @@ export const commands = {
       'lock-grace': { type: 'string', description: 'work: DEPRECATED and ignored — the broker lock is now auto-managed via --recovery-window.' },
       '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)' },
-      auto: { type: 'boolean', description: 'work: zero-config enrolment — serve ALL deployed agent job types read straight from the engine (no capability, no app enrol endpoint, no channel). Mutually exclusive with capability-resolved serving; has NO capability gate (serves any deployed agent job on the engine).' },
-      'auto-scope': { type: 'string', description: 'work: with --auto, narrow the served agent job types to those whose bpmn:process id equals or is prefixed by this value (one app/network). Default: all agent job types on the engine.' },
+      auto: { type: 'boolean', description: 'work / workforce add: zero-config enrolment — serve ALL deployed agent job types read straight from the engine (no capability, no app enrol endpoint, no channel). Mutually exclusive with capability-resolved serving (--roles); has NO capability gate (serves any deployed agent job on the engine). For workforce add it sets roles: "auto" in the manifest.' },
+      'auto-scope': { type: 'string', description: 'work / workforce add: with --auto, narrow the served agent job types to those whose bpmn:process id equals or is prefixed by this value (one app/network). Default: all agent job types on the engine. For workforce add it sets autoScope in the manifest.' },
       worker: { type: 'string', multiple: true, description: 'supervisor start: profile to launch as a supervised worker (repeatable)' },
-      instances: { type: 'string', description: `supervisor add: spawn N distinct auto-named instances of the profile in one call (default 1, max ${MAX_ADD_INSTANCES}; cannot combine with --name)` },
+      instances: { type: 'string', description: `supervisor add / workforce add: spawn/compose N distinct instances of the profile in one call (default 1, max ${MAX_ADD_INSTANCES}; for supervisor add cannot combine with --name)` },
       attach: { type: 'boolean', description: 'supervisor start: attach the interactive console after starting the daemon' },
+      profile: { type: 'string', description: `workforce: manifest name to operate on (default ${DEFAULT_WORKFORCE_MANIFEST}); each subcommand reads/writes <stateHome>/workforce/<name>.json` },
+      roles: { type: 'string', description: 'workforce add: comma-separated role list for the entry (→ --job-type <rank>:<role> at start); mutually exclusive with --auto' },
+      json: { type: 'boolean', description: 'workforce list/status: emit machine-readable JSON (for the install script / CI)' },
     },
     handler: async (args, flags) => {
       const logger = getLogger();
@@ -10017,6 +11102,9 @@ export const commands = {
           case 'supervisor':
             await supervisorCommand(req, flags);
             break;
+          case 'workforce':
+            await workforceCommand(req, flags);
+            break;
         }
       } catch (error) {
         logger.error(`nano ${req.subcommand} failed: ${error instanceof Error ? error.message : error}`);
@@ -10110,6 +11198,7 @@ function printUsage() {
   console.log('  c8ctl nano assign <profileName> <cap[,cap...]> [--name <n>] [--capabilities <a,b>]');
   console.log('  c8ctl nano work <profileName> [--auto [--auto-scope <p>]] [--arg <switch> ...] [--recovery-window <ms>] [--idle-timeout <ms>] [--job-timeout <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('  c8ctl nano supervisor [start|status|add|remove|restart|stop|logs|attach] ... (manage many workers from one terminal)');
+  console.log('  c8ctl nano workforce [add|remove|list|start|status|stop] ... [--profile <manifest>] (declarative, reusable fleet manifests)');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -10128,6 +11217,7 @@ function printUsage() {
   console.log('  assign   Grant new capabilities (roles) to an existing hire (additive; comma-separated; workers hot-reload)');
   console.log('  work     Run a hired profile as Nano job workers, polling for work until Ctrl-C');
   console.log('  supervisor  Run/manage a fleet of workers from one terminal (detachable console + non-interactive control)');
+  console.log('  workforce   Compose a reusable, declarative fleet manifest and reconcile it up/down (add|remove|list|start|status|stop)');
   console.log('');
   console.log('Options:');
   console.log('  <nodes>              Number of nodes to start (default 1)');