borgmcp 3.10.0 → 3.11.1

package/src/index.ts

@@ -139,6 +139,7 @@ import {
   openCodeLaunchBinding,
 } from './opencode-drone.js';
 import { installBorgPlugin } from './opencode-plugin.js';
+import { openCodeApiPasswordFromEnv } from './opencode-launch-trust.js';
 import { setModuleInjectOpenCode } from './log-stream.js';
 import {
   lifecycleSignalForMessage,
@@ -261,9 +262,15 @@ export async function connectOpenCodeRuntime(
     console.error(OPEN_CODE_PORT_MISSING_DIAGNOSTIC);
     return false;
   }
+  const apiPassword = openCodeApiPasswordFromEnv(env);
+  if (apiPassword === null) {
+    console.error('OpenCode API credential is missing or unverifiable; skipping OpenCode entry injection. Relaunch through borg.');
+    return false;
+  }
   const binding = openCodeLaunchBinding(configuredPort);
   await (deps.connect ?? connectOpenCodeDrone)({
     serverUrl: binding.serverUrl,
+    apiPassword,
     directory: active.worktree ?? findProjectRoot(),
     droneLabel: active.droneLabel,
     cubeName: active.name,

package/src/launch-all-cmd.ts

@@ -16,6 +16,9 @@ import { runPastelistBackend } from './backends/launch-all-pastelist.js';
 
 type Backend = 'tmux' | 'terminals' | 'pastelist';
 
+/** Internal strict-seam result: requested sessions were not dispatched. */
+export const LAUNCH_ALL_NO_DISPATCH_EXIT_CODE = 2;
+
 const TMUX_INSTALL_HINT =
   'borg launch-all: tmux not found.\n' +
   '  macOS:  brew install tmux\n' +
@@ -239,6 +242,12 @@ export interface RunLaunchAllOptions {
   sleep?: (ms: number) => Promise<void>;
   nowISO?: () => string;
   borgPath?: string;
+  /** Internal quickstart filter: launch only the requested staffed roster. */
+  droneIds?: readonly string[];
+  /** Fail when any requested registered drone cannot be discovered or launched. */
+  requireAllRequested?: boolean;
+  /** Internal resolved target avoids ambiguous same-name lookup during composition. */
+  targetCube?: { cubeId: string; name: string };
 }
 
 export async function runLaunchAll(
@@ -253,7 +262,7 @@ export async function runLaunchAll(
   const launchDelayMs = resolveLaunchDelayMs(args.flags.launchDelayMs, deps.getEnv('BORG_LAUNCH_DELAY_MS'));
 
   // 1. resolve target cube
-  const resolved = await resolveTargetCube(args, deps);
+  const resolved = opts.targetCube ?? await resolveTargetCube(args, deps);
   if ('error' in resolved) {
     deps.stderr(`borg launch-all: ${resolved.error}\n`);
     return 1;
@@ -264,7 +273,18 @@ export async function runLaunchAll(
   sweepStaleLocks(deps, cubeId, now());
 
   // 3. discover candidates
-  const discovered = await discoverDroneCandidates({ targetCubeId: cubeId, only: args.flags.only }, deps);
+  let discovered = await discoverDroneCandidates({ targetCubeId: cubeId, only: args.flags.only }, deps);
+  if (opts.droneIds !== undefined) {
+    const requested = new Set(opts.droneIds);
+    discovered = discovered.filter((candidate) => requested.has(candidate.droneId));
+    if (opts.requireAllRequested && discovered.length !== requested.size) {
+      deps.stderr(
+        `borg launch-all: found ${discovered.length} of ${requested.size} requested registered drone worktrees; ` +
+        'nothing was launched. Run `borg drones` to inspect the missing local registration.\n',
+      );
+      return 1;
+    }
+  }
   if (discovered.length === 0) {
     if (args.flags.only !== undefined) {
       deps.stdout(`No worktrees matched --only '${args.flags.only}' for cube '${cubeName}'\n`);
@@ -392,6 +412,14 @@ export async function runLaunchAll(
     }
     launchable.push(c);
   }
+  const terminalSkipCount = evictedCount + revokedCount + rejectedCount + trustMismatchCount + credentialRejectedCount;
+  if (opts.requireAllRequested && terminalSkipCount > 0) {
+    deps.stderr(
+      `borg launch-all: ${terminalSkipCount} requested registered drone(s) are not launchable; ` +
+      'nothing was launched. Resolve the cause reported above, then retry.\n',
+    );
+    return 1;
+  }
   if (launchable.length === 0) {
     // Accurate cause counts — an all-rejected sweep must NOT claim "evicted"
     // (and vice-versa). Only name a cause when at least one seat hit it.
@@ -441,6 +469,13 @@ export async function runLaunchAll(
     deps.stderr(sel.hardFail);
     return 1;
   }
+  if (sel.backend === 'pastelist' && opts.requireAllRequested) {
+    deps.stderr(
+      'borg launch-all: pastelist mode prints commands for manual use but does not launch sessions; ' +
+      'nothing was launched. Run `borg launch-all` separately to print the commands.\n',
+    );
+    return LAUNCH_ALL_NO_DISPATCH_EXIT_CODE;
+  }
   const sessionName = sanitizeSessionName(cubeName);
   const launchStartISO = nowISO();
 

package/src/opencode-drone.ts

@@ -1,12 +1,19 @@
 import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
-import { createHash, randomUUID } from 'crypto';
+import { createHash } from 'crypto';
 import { createServer } from 'node:net';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import {
   OPENCODE_INJECTED_ENTRY_METADATA_KEY,
   OPENCODE_WAKE_IDENTITY_METADATA_KEY,
+  OPENCODE_LAUNCH_CORRELATION_METADATA_KEY,
 } from './opencode-plugin.js';
+import {
+  createOpenCodeLaunchTrust,
+  isOpenCode256BitIdentity,
+  OPENCODE_SERVER_USERNAME,
+  type OpenCodeLaunchTrust,
+} from './opencode-launch-trust.js';
 
 const LOG_FILE = join(tmpdir(), 'borg-opencode-drone.log');
 function log(msg: string) {
@@ -16,6 +23,7 @@ function log(msg: string) {
 
 interface OpenCodeDroneState {
   serverUrl: string;
+  apiPassword: string;
   sessionId: string | null;
   sessionCreatedAt: number | null;
   knownRootSessionIds: string[];
@@ -39,6 +47,7 @@ let state: OpenCodeDroneState | null = null;
 
 interface ConnectDeps {
   serverUrl: string;
+  apiPassword: string;
   directory: string;
   droneLabel: string;
   cubeName: string;
@@ -124,27 +133,23 @@ interface SessionBinding {
 
 export interface OpenCodeLaunchKickoff {
   prompt: string;
-  nonce: string;
+  apiPassword: string;
+  correlationIdentity: string;
 }
 
-// This is correlation metadata, intentionally not an instruction to the
-// launched agent. A markdown comment keeps it benign in the user-visible
-// kickoff while preserving it in OpenCode's stored message text.
-const OPEN_CODE_LAUNCH_NONCE_MARKER = 'borg-opencode-correlation:';
-
 /**
- * Add a launch-unique identity to the OpenCode-only copy of the shared
- * kickoff. The prompt is what OpenCode records as its first user message, so
- * the launcher can later bind the MCP child to this precise launch instead of
- * guessing from a repeated kickoff's text or timestamp.
+ * Create independent launch trust for OpenCode without changing the shared
+ * kickoff text. The plugin writes the correlation identity to hidden metadata
+ * on the first qualifying human TextPart; the API password stays in env.
  */
 export function createOpenCodeLaunchKickoff(
   kickoff: string,
-  nonce: string = randomUUID(),
+  trust: Partial<OpenCodeLaunchTrust> = {},
 ): OpenCodeLaunchKickoff {
+  const launchTrust = createOpenCodeLaunchTrust(trust);
   return {
-    prompt: `${kickoff}\n\n<!-- ${OPEN_CODE_LAUNCH_NONCE_MARKER}${nonce} -->`,
-    nonce,
+    prompt: kickoff,
+    ...launchTrust,
   };
 }
 
@@ -161,9 +166,13 @@ function abandonOpenCodeDeliveries(current: OpenCodeDroneState | null): void {
 }
 
 export async function connectOpenCodeDrone(deps: ConnectDeps): Promise<void> {
+  if (!isOpenCode256BitIdentity(deps.apiPassword)) {
+    throw new Error('OpenCode API password is missing or unverifiable');
+  }
   abandonOpenCodeDeliveries(state);
   state = {
     serverUrl: deps.serverUrl,
+    apiPassword: deps.apiPassword,
     sessionId: null,
     sessionCreatedAt: null,
     knownRootSessionIds: [],
@@ -194,6 +203,17 @@ function apiUrl(path: string): string {
   return `${base}${path}${path.includes('?') ? '&' : '?'}directory=${encodeURIComponent(state!.directory)}`;
 }
 
+function authenticatedHeaders(headers: Record<string, string> = {}): Record<string, string> {
+  const password = state?.apiPassword;
+  if (!isOpenCode256BitIdentity(password)) {
+    throw new Error('OpenCode API password is missing or unverifiable');
+  }
+  return {
+    ...headers,
+    Authorization: `Basic ${Buffer.from(`${OPENCODE_SERVER_USERNAME}:${password}`).toString('base64')}`,
+  };
+}
+
 const FETCH_TIMEOUT = 10_000;
 
 async function rawGet(path: string): Promise<{ status: number; body: string }> {
@@ -201,7 +221,7 @@ async function rawGet(path: string): Promise<{ status: number; body: string }> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
   try {
-    const res = await fetch(url, { signal: controller.signal });
+    const res = await fetch(url, { headers: authenticatedHeaders(), signal: controller.signal });
     const body = await res.text();
     return { status: res.status, body };
   } finally {
@@ -216,7 +236,7 @@ async function rawPost(path: string, bodyObj: unknown): Promise<{ status: number
   try {
     const res = await fetch(url, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: authenticatedHeaders({ 'Content-Type': 'application/json' }),
       signal: controller.signal,
       body: JSON.stringify(bodyObj),
     });
@@ -453,28 +473,29 @@ async function findUnseenTopLevelSession(knownRootSessionIds: string[]): Promise
   }
 }
 
-function kickoffMessageTime(messages: OCMessage[], nonce: string): number | null {
-  let latest: number | null = null;
+function launchCorrelationMatchCount(messages: OCMessage[], correlationIdentity: string): number {
+  let count = 0;
   for (const message of messages) {
-    if (message.info?.role && message.info.role !== 'user') continue;
-    const matchesLaunchNonce = message.parts?.some(
-      (part) => part.type === 'text' && part.text?.includes(`${OPEN_CODE_LAUNCH_NONCE_MARKER}${nonce}`),
-    );
-    if (!matchesLaunchNonce) continue;
-    const created = message.info?.time?.created ?? 0;
-    latest = latest === null ? created : Math.max(latest, created);
+    if (message.info?.role !== 'user') continue;
+    for (const part of message.parts ?? []) {
+      if (
+        part.type === 'text' &&
+        part.metadata?.[OPENCODE_LAUNCH_CORRELATION_METADATA_KEY] === correlationIdentity
+      ) {
+        count++;
+      }
+    }
   }
-  return latest;
+  return count;
 }
 
 /**
  * The launch process is the only place allowed to discover a session from the
- * server. It chooses the session that contains this launch's unique nonce,
- * rather than choosing by repeated kickoff text or session creation time. A
- * fork is therefore allowed only when it was explicitly selected for this
- * launch and received the nonce-bearing kickoff.
+ * server. It chooses the session containing exactly one hidden metadata match,
+ * never repeated prompt text, timestamps, or newest-session order. A fork is
+ * therefore allowed only when it received this launch's correlation metadata.
  */
-async function findLaunchSession(nonce: string): Promise<{
+async function findLaunchSession(correlationIdentity: string): Promise<{
   session: OCSession;
   knownRootSessionIds: string[];
 } | null> {
@@ -485,25 +506,17 @@ async function findLaunchSession(nonce: string): Promise<{
     const knownRootSessionIds = sessions
       .filter(isTopLevelSession)
       .map((session) => session.id);
-    const candidates = await Promise.all(sessions.map(async (session) => {
-      try {
-        const messageTime = kickoffMessageTime(
-          await listSessionMessages(session.id),
-          nonce,
-        );
-        return messageTime === null ? null : { session, messageTime };
-      } catch {
-        return null;
-      }
-    }));
-    const matched = candidates.filter(
-      (candidate): candidate is { session: OCSession; messageTime: number } => candidate !== null,
-    );
-    if (matched.length === 0) return null;
-    const session = matched.reduce((best, candidate) =>
-      candidate.messageTime > best.messageTime ? candidate : best,
-    ).session;
-    return { session, knownRootSessionIds };
+    const candidates = await Promise.all(sessions.map(async (session) => ({
+      session,
+      matchCount: launchCorrelationMatchCount(
+        await listSessionMessages(session.id),
+        correlationIdentity,
+      ),
+    })));
+    const totalMatches = candidates.reduce((total, candidate) => total + candidate.matchCount, 0);
+    if (totalMatches !== 1) return null;
+    const matched = candidates.find((candidate) => candidate.matchCount === 1);
+    return matched ? { session: matched.session, knownRootSessionIds } : null;
   } catch {
     return null;
   }
@@ -795,11 +808,15 @@ async function processOpenCodeDeliveries(owner: OpenCodeDroneState): Promise<voi
 
 /**
  * Wait for the OpenCode HTTP server, then capture the session that received
- * this launch's nonce-bearing `--prompt` kickoff. The binding survives the separate
- * MCP-child process, which must never fall back to a newest-session heuristic.
+ * this launch's metadata-correlated `--prompt` kickoff. The binding survives
+ * the separate MCP-child process, which must never fall back to a newest-session heuristic.
  */
 export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promise<boolean> {
   if (!state?.connected) { log('kickoff: not connected'); return false; }
+  if (!isOpenCode256BitIdentity(launch.correlationIdentity)) {
+    log('kickoff: correlation identity missing or unverifiable');
+    return false;
+  }
 
   try {
     // Wait for the server.
@@ -815,9 +832,9 @@ export async function injectInitialKickoff(launch: OpenCodeLaunchKickoff): Promi
     }
 
     // Capture the launch-selected session, including explicit resume/fork
-    // targets. Unrelated sessions do not contain this launch's nonce.
+    // targets. Unrelated sessions do not contain this launch's metadata identity.
     for (let i = 0; i < 30; i++) {
-      const binding = await findLaunchSession(launch.nonce);
+      const binding = await findLaunchSession(launch.correlationIdentity);
       if (binding) {
         saveBinding(binding.session, binding.knownRootSessionIds);
         log(`kickoff: bound session ${binding.session.id.slice(0, 8)}…`);

package/src/opencode-launch-trust.ts

@@ -0,0 +1,46 @@
+import { randomBytes } from 'node:crypto';
+
+export const OPENCODE_SERVER_USERNAME = 'opencode';
+export const OPENCODE_SERVER_USERNAME_ENV = 'OPENCODE_SERVER_USERNAME';
+export const OPENCODE_SERVER_PASSWORD_ENV = 'OPENCODE_SERVER_PASSWORD';
+export const BORG_OPENCODE_LAUNCH_CORRELATION_ENV = 'BORG_OPENCODE_LAUNCH_CORRELATION';
+export const OPENCODE_SERVER_PASSWORD_REFERENCE = `{env:${OPENCODE_SERVER_PASSWORD_ENV}}`;
+
+export interface OpenCodeLaunchTrust {
+  apiPassword: string;
+  correlationIdentity: string;
+}
+
+function random256BitIdentity(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+export function createOpenCodeLaunchTrust(overrides: Partial<OpenCodeLaunchTrust> = {}): OpenCodeLaunchTrust {
+  const trust = {
+    apiPassword: overrides.apiPassword ?? random256BitIdentity(),
+    correlationIdentity: overrides.correlationIdentity ?? random256BitIdentity(),
+  };
+  if (!isOpenCode256BitIdentity(trust.apiPassword) || !isOpenCode256BitIdentity(trust.correlationIdentity)) {
+    throw new Error('OpenCode launch trust must contain independent 256-bit identities');
+  }
+  if (trust.apiPassword === trust.correlationIdentity) {
+    throw new Error('OpenCode API password and correlation identity must be independent');
+  }
+  return trust;
+}
+
+export function isOpenCode256BitIdentity(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  try {
+    const decoded = Buffer.from(value, 'base64url');
+    return decoded.length === 32 && decoded.toString('base64url') === value;
+  } catch {
+    return false;
+  }
+}
+
+export function openCodeApiPasswordFromEnv(env: NodeJS.ProcessEnv): string | null {
+  if (env[OPENCODE_SERVER_USERNAME_ENV] !== OPENCODE_SERVER_USERNAME) return null;
+  const password = env[OPENCODE_SERVER_PASSWORD_ENV];
+  return isOpenCode256BitIdentity(password) ? password : null;
+}

package/src/opencode-plugin.ts

@@ -20,6 +20,7 @@ const COMPACT_FALLBACK =
 export const OPENCODE_INJECTED_ENTRY_METADATA_KEY = 'borgOpenCodeInjectedEntry';
 export const OPENCODE_WAKE_IDENTITY_METADATA_KEY = 'borgOpenCodeWakeIdentity';
 export const OPENCODE_RECOVERY_METADATA_KEY = 'borgOpenCodeSessionOrientation';
+export const OPENCODE_LAUNCH_CORRELATION_METADATA_KEY = 'borgOpenCodeLaunchCorrelation';
 const PLUGIN_REL_PATH = path.join('.config', 'opencode', 'plugins', 'borg-orient.js');
 
 export interface OpenCodePluginCoreDeps {
@@ -45,6 +46,8 @@ export interface OpenCodePluginCoreOptions {
   confirmationPollAttempts: number;
   pollDelayMs: number;
   compactFallback: string;
+  launchCorrelationMetadataKey: string;
+  launchCorrelationIdentity: string;
 }
 
 /** Pure, dependency-injected behavior core. Its emitted JavaScript function
@@ -55,6 +58,7 @@ export function createOpenCodePluginCore(
 ) {
   const claimedSessions = new Set<string>();
   const humanPromptSessions = new Set<string>();
+  let launchCorrelationAttached = false;
   const textParts = (message: any): any[] => Array.isArray(message?.parts)
     ? message.parts.filter((part: any) => part?.type === 'text' && typeof part.text === 'string')
     : [];
@@ -129,7 +133,28 @@ export function createOpenCodePluginCore(
       output: { message: unknown; parts: any[] },
     ): Promise<void> => {
       if (!options.enabled) return;
-      const current = { info: { role: 'user' }, parts: [...output.parts] };
+      let current = { info: { role: 'user' }, parts: [...output.parts] };
+      if (
+        !launchCorrelationAttached &&
+        options.launchCorrelationIdentity &&
+        !isInjectedEntry(current) &&
+        !isOwnedRecovery(current)
+      ) {
+        const index = output.parts.findIndex((part) =>
+          part?.type === 'text' && typeof part.text === 'string');
+        if (index >= 0) {
+          const part = output.parts[index];
+          output.parts[index] = {
+            ...part,
+            metadata: {
+              ...(part.metadata && typeof part.metadata === 'object' ? part.metadata : {}),
+              [options.launchCorrelationMetadataKey]: options.launchCorrelationIdentity,
+            },
+          };
+          launchCorrelationAttached = true;
+          current = { info: { role: 'user' }, parts: [...output.parts] };
+        }
+      }
       if (!isInjectedEntry(current) && !isOwnedRecovery(current)) {
         // chat.message fires before the user message is persisted. Record the
         // human turn synchronously so recovery cannot race that short gap.
@@ -165,6 +190,7 @@ export function buildBorgPluginSource(version: string): string {
 const createCore = ${createOpenCodePluginCore.toString()};
 const evaluateAudit = ${evaluateLogAudit.toString()};
 export default async function (ctx) {
+  const launchCorrelationIdentity = process.env.BORG_OPENCODE_LAUNCH_CORRELATION || '';
   const runRegen = async (source) => {
     const input = JSON.stringify({ source });
     const result = await ctx.$\`printf '%s' \${input} | borg-regen\`.quiet().nothrow();
@@ -204,8 +230,12 @@ export default async function (ctx) {
     confirmationPollAttempts: 6,
     pollDelayMs: 200,
     compactFallback: COMPACT_FALLBACK,
+    launchCorrelationMetadataKey: OPENCODE_LAUNCH_CORRELATION_METADATA_KEY,
   })},
     enabled: process.env.BORG_SESSION === '1',
+    launchCorrelationIdentity: /^[A-Za-z0-9_-]{43}$/.test(launchCorrelationIdentity)
+      ? launchCorrelationIdentity
+      : '',
   });
 }
 `;

package/src/parse-clone-args.ts

@@ -0,0 +1,44 @@
+import { redactCloneSecrets } from './clone-security.js';
+
+export interface CloneArgs {
+  repositoryUrl: string;
+  destination?: string;
+  noLaunch: boolean;
+}
+
+export type ParseCloneResult =
+  | { ok: true; args: CloneArgs }
+  | { ok: false; error: string };
+
+export function parseCloneArgs(rawArgs: readonly string[]): ParseCloneResult {
+  let repositoryUrl: string | undefined;
+  let destination: string | undefined;
+  let noLaunch = false;
+  for (const arg of rawArgs) {
+    if (arg === '--no-launch') {
+      if (noLaunch) return { ok: false, error: '--no-launch was provided more than once' };
+      noLaunch = true;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      const option = arg.startsWith('--') ? arg.split('=', 1)[0] : arg.slice(0, 2);
+      return { ok: false, error: `unknown option ${option}; the only option is --no-launch` };
+    }
+    if (repositoryUrl === undefined) repositoryUrl = arg;
+    else if (destination === undefined) destination = arg;
+    else return { ok: false, error: 'unexpected extra argument' };
+  }
+  if (!repositoryUrl) return { ok: false, error: 'a repository URL is required' };
+  return {
+    ok: true,
+    args: {
+      repositoryUrl,
+      ...(destination === undefined ? {} : { destination }),
+      noLaunch,
+    },
+  };
+}
+
+export function safeCloneParseError(result: Extract<ParseCloneResult, { ok: false }>): string {
+  return redactCloneSecrets(result.error);
+}

package/src/parse-quickstart-args.ts

@@ -0,0 +1,54 @@
+import { NEW_CUBE_TEMPLATE_PRESENTATIONS } from 'borgmcp-shared/templates';
+
+export interface QuickstartRoleRequest {
+  slug: string;
+  count: number;
+}
+
+export interface QuickstartArgs {
+  template?: string;
+  roles: QuickstartRoleRequest[];
+  yes: boolean;
+}
+
+export type ParseQuickstartResult =
+  | { ok: true; args: QuickstartArgs }
+  | { ok: false; error: string };
+
+const templates = new Set<string>(NEW_CUBE_TEMPLATE_PRESENTATIONS.map(({ name }) => name));
+
+function parseRole(value: string): QuickstartRoleRequest | null {
+  const match = /^([a-z0-9]+(?:-[a-z0-9]+)*)(?::([1-9]\d*))?$/.exec(value);
+  if (!match) return null;
+  const count = match[2] === undefined ? 1 : Number(match[2]);
+  return Number.isSafeInteger(count) ? { slug: match[1], count } : null;
+}
+
+export function parseQuickstartArgs(rawArgs: readonly string[]): ParseQuickstartResult {
+  const args: QuickstartArgs = { roles: [], yes: false };
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === '--yes' || arg === '-y') {
+      args.yes = true;
+      continue;
+    }
+    if (arg === '--template') {
+      const value = rawArgs[++i];
+      if (!value) return { ok: false, error: '--template requires software-dev, starter, or local-model' };
+      if (!templates.has(value)) return { ok: false, error: `unknown template '${value}'; choose software-dev, starter, or local-model` };
+      if (args.template !== undefined) return { ok: false, error: '--template was provided more than once' };
+      args.template = value;
+      continue;
+    }
+    if (arg === '--role') {
+      const value = rawArgs[++i];
+      if (!value) return { ok: false, error: '--role requires <slug>[:<count>]' };
+      const role = parseRole(value);
+      if (!role) return { ok: false, error: `invalid role '${value}'; use <slug>[:<positive-count>]` };
+      args.roles.push(role);
+      continue;
+    }
+    return { ok: false, error: `unknown option: ${arg}. Supported: --template, --role, --yes/-y` };
+  }
+  return { ok: true, args };
+}