hub-launch 1.21.0 → 1.22.0

package/dist/commands/launch.js

@@ -4,12 +4,14 @@ import chalk from 'chalk';
 import os from 'os';
 import path from 'path';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { join, isAbsolute } from 'path';
 import { parse } from 'dotenv';
 import { logger } from '../utils/logger.js';
 import { GitService } from '../services/git/GitService.js';
 import { PlanService } from '../services/plan/PlanService.js';
-import { HulaApiClient } from '../services/api/HulaApiClient.js';
+import { ConfigLoader } from '../config/index.js';
+import { HulaApiClient, ApiError, } from '../services/api/HulaApiClient.js';
+import { GroupLaunchService, validateGroupId, } from '../services/group/GroupLaunchService.js';
 import { TempFileService } from '../services/logs/TempFileService.js';
 import { EditorService } from '../services/editor/EditorService.js';
 import { executeUpload } from './upload.js';
@@ -31,6 +33,20 @@ const DEFAULT_CONTAINER_RESOURCES = { cpu: 2, memory: 4, disk: 10 };
  * Usage: hula launch --show <name>
  * Usage: hula launch --logs <name>
  */
+/**
+ * Commander accumulator for the repeatable `--plan <repo>=<path>` option.
+ * Each occurrence is parsed as `repoName=relativePath` and merged into the
+ * override map. A missing `=` throws a clear error.
+ */
+export function collectPlanOverrides(value, previous) {
+    const eq = value.indexOf('=');
+    if (eq <= 0) {
+        throw new Error(`Invalid --plan override "${value}". Expected <repoName>=<path>.`);
+    }
+    const repo = value.slice(0, eq);
+    const planPath = value.slice(eq + 1);
+    return { ...previous, [repo]: planPath };
+}
 export function launchCommand(program, config) {
     program
         .command('launch [issueName] [planPath]')
@@ -64,8 +80,22 @@ export function launchCommand(program, config) {
         .option('--lines <n>', 'Number of log lines to show (default: 100)', parseInt)
         .option('--type <type>', 'Log type to fetch: log or output (default: log)')
         .option('--editor', 'Open logs in editor instead of printing to stdout')
+        // ── Multi-repo feature groups (client-side fan-out) ────────────────────
+        // NOTE: this `--folder` (a PARENT directory that contains sibling repos) is
+        // DIFFERENT from /hula-plan's `--folder` (a plans SUBDIRECTORY). See README.
+        .option('--folder <path>', 'Launch the plan in every initialized repo under this folder as one feature group')
+        .option('--group-id <id>', 'Use this group id instead of generating one (join/retry an existing group)')
+        .option('--plan <repo>=<path>', 'Override the auto-resolved plan for one repo in --folder mode (repeatable)', collectPlanOverrides, {})
+        .option('--show-group [id]', 'Show combined status for a feature group (id optional inside a member repo)')
+        .option('--yes', 'Skip the group-launch confirmation and allow plan auto-resolve without a TTY (used by the /hula-launch skill)')
         .action(async (issueName, planPath, options) => {
         try {
+            // Handle --show-group flag (read-only group status). Routed before
+            // the other read flags and before any folder/launch work.
+            if (options.showGroup !== undefined) {
+                await showGroupStatus(config, options.showGroup, options);
+                return;
+            }
             // Handle --show flag
             if (options.show) {
                 await showJobStatus(config, options.show, options);
@@ -83,6 +113,21 @@ export function launchCommand(program, config) {
                 logger.error(killFlagError);
                 process.exit(1);
             }
+            // Validate the multi-repo `--folder` / `--group-id` / `--plan` flag
+            // combination before any work.
+            const folderFlagError = validateFolderFlags(options, Boolean(planPath));
+            if (folderFlagError) {
+                logger.error(folderFlagError);
+                process.exit(1);
+            }
+            // Validate an explicitly-supplied group id against the server format.
+            if (typeof options.groupId === 'string') {
+                const groupIdError = validateGroupId(options.groupId);
+                if (groupIdError) {
+                    logger.error(groupIdError);
+                    process.exit(1);
+                }
+            }
             // Validate per-step config + --skip-regression against the two
             // server-parity cross-field rules before any credential resolution or
             // network call. On conflict, fail fast with the server's exact wording.
@@ -91,6 +136,21 @@ export function launchCommand(program, config) {
                 logger.error(stepsValidation.error);
                 process.exit(1);
             }
+            // Multi-repo fan-out: --folder launches (or kills) one ordinary
+            // single-repo job per discovered repo, correlated by a shared groupId.
+            if (options.folder) {
+                if (!issueName) {
+                    logger.error('Usage: hula launch <issueName> --folder <path>');
+                    process.exit(1);
+                }
+                if (options.kill) {
+                    await executeGroupKill(config, issueName, options);
+                }
+                else {
+                    await executeGroupLaunch(config, issueName, options);
+                }
+                return;
+            }
             // --kill is a cancel-only path: it needs ONLY the tracking name (no
             // plan path) and routes to the dedicated executeKill function.
             if (options.kill) {
@@ -158,6 +218,43 @@ export function validateKillFlags(options) {
 export function requiresPlanPath(options) {
     return !options.kill;
 }
+/**
+ * Validate the multi-repo `--folder` / `--group-id` / `--plan` flag matrix.
+ *
+ * - `--folder` resolves plans per repository, so it is incompatible with a
+ *   positional `<planPath>` and with the read/resume flags `--show`, `--logs`,
+ *   `--resume`, `--fix`.
+ * - `--plan` (per-repo override) only makes sense with `--folder`.
+ * - `--group-id` alone (no `--folder`) is allowed — it attaches a single-repo
+ *   launch to an existing group.
+ * - `--kill --folder` is allowed (cancel-only fan-out).
+ *
+ * Returns an error message when the combination is invalid, or `null` when OK.
+ */
+export function validateFolderFlags(options, hasPlanPathPositional) {
+    if (options.folder) {
+        if (hasPlanPathPositional) {
+            return '--folder resolves plans per repository; use --plan <repo>=<path> to override a specific repo';
+        }
+        const incompatible = [
+            { key: 'show', flag: '--show' },
+            { key: 'logs', flag: '--logs' },
+            { key: 'resume', flag: '--resume' },
+            { key: 'fix', flag: '--fix' },
+        ];
+        for (const { key, flag } of incompatible) {
+            const value = options[key];
+            if (value !== undefined && value !== false) {
+                return `--folder cannot be combined with ${flag}`;
+            }
+        }
+    }
+    const hasPlanOverrides = options.plan !== undefined && Object.keys(options.plan).length > 0;
+    if (hasPlanOverrides && !options.folder) {
+        return '--plan requires --folder (it overrides a per-repo plan in folder mode)';
+    }
+    return null;
+}
 /**
  * Derive the request `conflictMode` from the CLI flags (plus an optional explicit
  * override used when re-invoking after an interactive 409 resolution).
@@ -352,7 +449,11 @@ function printFreeTierError() {
  * If the config records 'free', calls the API and updates the config on success.
  * Returns false (and prints the error) when the user is not on Pro.
  */
-async function verifyProTier(config, serverUrl, apiKey) {
+async function verifyProTier(config, serverUrl, apiKey, 
+// Repo root whose config file records the verified tier. Group mode passes
+// the member repo's path — process.cwd() there is the parent folder, which
+// has no .hublaunch and would silently drop the persistence every run.
+repoRoot = process.cwd()) {
     if (config.usageTier === 'pro') {
         return true;
     }
@@ -363,7 +464,7 @@ async function verifyProTier(config, serverUrl, apiKey) {
         });
         const plan = response.data?.plan;
         if (plan === 'pro') {
-            const saved = updateUsageTierInConfig(process.cwd(), 'pro');
+            const saved = updateUsageTierInConfig(repoRoot, 'pro');
             if (saved) {
                 logger.success('Subscription verified as Pro — config updated for future launches.');
             }
@@ -390,73 +491,207 @@ async function verifyProTier(config, serverUrl, apiKey) {
         return true;
     }
 }
+/**
+ * Assemble the `POST /api/v1/ralph-run` request body from already-resolved
+ * inputs. Fields are inserted in a fixed order and only when present, so a
+ * launch with no group flag produces a body byte-identical to the pre-fan-out
+ * CLI (verified by unit test — AC5).
+ */
+export function buildRalphRunRequestBody(input) {
+    const body = {
+        issueName: input.issueName,
+        planPath: input.planPath,
+        repositoryId: input.repositoryId,
+    };
+    if (input.duration !== undefined) {
+        body.duration = input.duration;
+    }
+    // Keep 'ralphPath' property name for server API compatibility
+    // even though the CLI option is now '--launch'
+    if (input.launchPath) {
+        body.ralphPath = input.launchPath;
+    }
+    // Handle worktree: commander sets it to false for --no-worktree
+    if (input.worktree === false) {
+        body.worktree = false;
+    }
+    else if (typeof input.worktree === 'string') {
+        body.worktree = input.worktree;
+    }
+    if (input.resume !== undefined) {
+        body.resume = input.resume;
+    }
+    if (input.fix) {
+        body.fix = input.fix;
+    }
+    if (input.regression) {
+        body.regression = true;
+    }
+    // Maps to RalphRunRequest.steps (hula-server PR #442).
+    if (input.steps) {
+        body.steps = input.steps;
+    }
+    // Maps to RalphRunRequest.test (hula-server PR #367).
+    if (input.test) {
+        body.test = true;
+    }
+    // Maps to RalphRunRequest.conflictMode (hula-server PR #391). Only added for
+    // 'killAndRelaunch' — the server default 'reject' is expressed by omitting.
+    if (input.conflictMode) {
+        body.conflictMode = input.conflictMode;
+    }
+    // Maps to RalphRunRequest.groupId (hula-server PR #505): the shared feature-
+    // group label correlating the N single-repo launches of a `--folder` fan-out.
+    // Omitted entirely for single-repo launches — the server default (ungrouped)
+    // is expressed by omitting the key, keeping non-group bodies byte-identical
+    // (same omit-when-absent pattern as `test`/`conflictMode` above).
+    if (input.groupId) {
+        body.groupId = input.groupId;
+    }
+    if (input.verbose) {
+        body.verbose = true;
+    }
+    if (input.handoff) {
+        body.handoff = input.handoff;
+    }
+    // Maps to RalphRunRequest.clientSessionId (hula-server PR #419).
+    if (input.clientSessionId) {
+        body.clientSessionId = input.clientSessionId;
+    }
+    body.anthropicApiKey = input.anthropicApiKey;
+    if (input.containerResources) {
+        body.containerResources = input.containerResources;
+    }
+    if (input.updateNotificationUrl) {
+        body.updateNotificationUrl = input.updateNotificationUrl;
+    }
+    if (input.updateNotificationNameTag) {
+        body.updateNotificationNameTag = input.updateNotificationNameTag;
+    }
+    if (input.githubToken) {
+        body.githubToken = input.githubToken;
+    }
+    if (input.envVars) {
+        body.envVars = input.envVars;
+    }
+    return body;
+}
+/**
+ * Single-repo launch entry point. Runs the plan-sync/upload check, then defers
+ * the body-build + POST to {@link launchSingleRepo} in single mode (keeps the
+ * interactive 409 resolver and process-exit-on-error behavior).
+ */
 async function executeLaunch(config, issueName, planPath, options, 
 // Explicit conflict mode override. Set when re-invoking after the interactive
 // 409 resolver picks "kill and relaunch" — it both forces the server to
 // cancel+relaunch and (being non-undefined) suppresses re-entering the prompt.
 conflictModeOverride) {
     logger.section('Launch');
+    const result = await launchSingleRepo(config, process.cwd(), issueName, planPath, options, {
+        mode: 'single',
+        interactive409: true,
+        conflictModeOverride,
+        groupId: options.groupId,
+    });
+    // In single mode every fatal error already called process.exit inside
+    // launchSingleRepo (or the interactive 409 resolver handled the flow); a
+    // returned failure that reached here still exits non-zero for safety.
+    if (!result.ok) {
+        process.exit(1);
+    }
+}
+/**
+ * Body-build + POST core of a launch, reused by both the single-repo path and
+ * the `--folder` fan-out. In single mode fatal errors call `process.exit` and a
+ * reject-409 opens the interactive resolver; in group mode fatal errors are
+ * returned as a failed {@link RepoLaunchResult} so the fan-out can continue.
+ *
+ * @param repoConfig - The repository's loaded config.
+ * @param repoRoot - Absolute path to the repository root (cwd for git/env/.env).
+ * @param issueName - Tracking name for the launch.
+ * @param planPath - Plan path (repo-relative or absolute).
+ * @param options - Parsed CLI options.
+ * @param ctx - Mode + shared-once context (see {@link SingleRepoLaunchContext}).
+ */
+async function launchSingleRepo(repoConfig, repoRoot, issueName, planPath, options, ctx) {
+    const isGroup = ctx.mode === 'group';
     // Effective conflict mode: an explicit override (from the 409 resolver) or the
     // --kill-and-relaunch flag. Undefined = default 'reject' (byte-identical body).
-    const conflictMode = deriveConflictMode(options, conflictModeOverride);
+    const conflictMode = deriveConflictMode(options, ctx.conflictModeOverride);
     // Check if plan is synced to origin/main
-    const planSyncStatus = await checkPlanSyncStatus(config, planPath);
+    const planSyncStatus = await checkPlanSyncStatus(repoConfig, planPath, repoRoot);
     if (!planSyncStatus.synced) {
         if (planSyncStatus.location === 'not-found') {
             logger.error('Plan not found locally or on origin/main');
             logger.info('Make sure you created the plan with /hula-plan');
+            if (isGroup)
+                return { ok: false, message: 'Plan not found locally or on origin/main' };
             process.exit(1);
         }
         // Plan exists locally but not on origin/main - auto-upload
         logger.info('Plan found locally, pushing to origin/main...');
         try {
-            await executeUpload(config, planPath);
+            await executeUpload(repoConfig, planPath, repoRoot);
             logger.success('Plan synced to origin/main');
             logger.blank();
         }
         catch (uploadError) {
-            logger.error('Failed to upload plan:');
-            logger.error(uploadError instanceof Error
+            const msg = uploadError instanceof Error
                 ? uploadError.message
-                : String(uploadError));
+                : String(uploadError);
+            logger.error('Failed to upload plan:');
+            logger.error(msg);
+            if (isGroup)
+                return { ok: false, message: `Failed to upload plan: ${msg}` };
             process.exit(1);
         }
     }
     // Get server URL and API key
-    const serverUrl = options.url || config.hulaProjectUrl || HULA_PROJECT_URL;
-    const apiKey = options.apiKey || config.hulaApiKey || process.env.HULA_API_KEY;
+    const serverUrl = options.url || repoConfig.hulaProjectUrl || HULA_PROJECT_URL;
+    const apiKey = options.apiKey || repoConfig.hulaApiKey || process.env.HULA_API_KEY;
     if (!apiKey) {
         logger.error('No API key configured.');
         logger.info('Set hulaApiKey in your config or use --api-key option.');
         logger.info('You can also set HULA_API_KEY environment variable.');
         logger.info("Run 'hula login' to authenticate with hula-project.");
+        if (isGroup)
+            return { ok: false, message: 'No API key configured' };
         process.exit(1);
     }
-    // Verify the user is on the Pro tier before proceeding
-    const isProUser = await verifyProTier(config, serverUrl, apiKey);
-    if (!isProUser) {
-        process.exit(1);
+    // Verify the user is on the Pro tier before proceeding (skipped in group mode
+    // where the check ran once against the first repo's key).
+    if (!ctx.proTierVerified) {
+        const isProUser = await verifyProTier(repoConfig, serverUrl, apiKey);
+        if (!isProUser) {
+            if (isGroup)
+                return { ok: false, message: 'Not on the Pro tier' };
+            process.exit(1);
+        }
     }
-    // Get project ID - from config or detect from git
-    const repositoryId = await resolveProject(config);
+    // Get project ID - from config or detect from git (repo cwd for the fallback)
+    const repositoryId = ctx.repositoryId ?? (await resolveProject(repoConfig, undefined, repoRoot));
     // Validate fix requires resume
     if (options.fix && options.resume === undefined) {
         logger.error('--fix requires --resume to be set');
+        if (isGroup)
+            return { ok: false, message: '--fix requires --resume to be set' };
         process.exit(1);
     }
     // Validate resume range
     if (options.resume !== undefined &&
         (options.resume < 1 || options.resume > 9)) {
         logger.error('--resume must be between 1 and 9');
+        if (isGroup)
+            return { ok: false, message: '--resume must be between 1 and 9' };
         process.exit(1);
     }
     // Build the API endpoint
     const endpoint = `${serverUrl.replace(/\/$/, '')}/api/v1/ralph-run`;
     const updateNotificationUrl = options.updateNotificationUrl ||
-        config.updateNotificationUrl ||
+        repoConfig.updateNotificationUrl ||
         process.env.HULA_UPDATE_NOTIFICATION_URL;
     const updateNotificationNameTag = options.updateNotificationNameTag ||
-        config.updateNotificationNameTag ||
+        repoConfig.updateNotificationNameTag ||
         process.env.HULA_UPDATE_NOTIFICATION_NAME_TAG;
     logger.info(`Triggering launch job...`);
     logger.log(`  Issue Name: ${issueName}`);
@@ -483,93 +718,31 @@ conflictModeOverride) {
         logger.log(`  Test Mode: yes (mock Claude)`);
     if (options.handoff)
         logger.log(`  Handoff To: ${options.handoff}`);
+    if (ctx.groupId)
+        logger.log(`  Group: ${ctx.groupId}`);
     if (updateNotificationUrl)
         logger.log(`  Notify on completion: enabled`);
     if (updateNotificationNameTag)
         logger.log(`  Notify tag: ${updateNotificationNameTag}`);
-    if (config.envVars) {
-        if (config.envVars === 'all') {
+    if (repoConfig.envVars) {
+        if (repoConfig.envVars === 'all') {
             logger.log(`  Environment Variables: all (from .env)`);
         }
-        else if (config.envVars.length > 0) {
-            logger.log(`  Environment Variables: ${config.envVars.length} configured`);
+        else if (repoConfig.envVars.length > 0) {
+            logger.log(`  Environment Variables: ${repoConfig.envVars.length} configured`);
         }
     }
     logger.blank();
-    // Build request body
-    const requestBody = {
-        issueName,
-        planPath,
-        repositoryId,
-    };
-    if (options.duration !== undefined) {
-        requestBody.duration = options.duration;
-    }
-    // Keep 'ralphPath' property name for server API compatibility
-    // even though the CLI option is now '--launch'
-    if (options.launch) {
-        requestBody.ralphPath = options.launch;
-    }
-    // Handle worktree: commander sets it to false for --no-worktree
-    if (options.worktree === false) {
-        requestBody.worktree = false;
-    }
-    else if (typeof options.worktree === 'string') {
-        requestBody.worktree = options.worktree;
-    }
-    if (options.resume !== undefined) {
-        requestBody.resume = options.resume;
-    }
-    if (options.fix) {
-        requestBody.fix = options.fix;
-    }
-    if (options.regression) {
-        requestBody.regression = true;
-    }
-    // Maps to RalphRunRequest.steps (hula-server PR #442): per-pipeline-step model,
-    // iteration-cap, and skip overrides from the config-file `steps` block plus the
-    // --skip-regression flag. resolveSteps() re-runs the same validation the action
-    // handler already passed (pure function), and returns `undefined` when there's
-    // nothing to send — omitted entirely then, keeping non-steps request bodies
-    // byte-identical (same pattern as `test`/`conflictMode` above).
-    const stepsResult = resolveSteps(config.steps, options.skipRegression, options.regression);
-    if (stepsResult.steps) {
-        requestBody.steps = stepsResult.steps;
-    }
-    // Maps to RalphRunRequest.test (hula-server PR #367): when true, the server
-    // runs the full production pipeline but swaps the real Claude CLI for a mock
-    // executable — a fast E2E run that still creates a real PR. Omitted entirely
-    // when --test is absent, keeping non-test request bodies byte-identical.
-    if (options.test) {
-        requestBody.test = true;
-    }
-    // Maps to RalphRunRequest.conflictMode (hula-server PR #391). Only added for
-    // 'killAndRelaunch' — the server default 'reject' is expressed by omitting the
-    // key entirely, keeping the default-launch request body byte-identical to
-    // before this change (same pattern as `test` above).
-    if (conflictMode) {
-        requestBody.conflictMode = conflictMode;
-    }
-    if (options.verbose) {
-        requestBody.verbose = true;
-    }
-    if (options.handoff) {
-        requestBody.handoff = options.handoff;
-    }
-    // Maps to RalphRunRequest.clientSessionId (hula-server PR #419): the Claude
-    // Code session id of the chat session that ran /hula-launch, captured by the
-    // hula-session-hook moments before this CLI runs. Provenance for client
-    // tooling (/hula-verify, /hula-info). Omitted entirely when no hook capture
-    // exists (plain-terminal launches, CI), keeping those request bodies
-    // byte-identical — same pattern as `test` above.
+    // Maps to RalphRunRequest.steps (hula-server PR #442). resolveSteps() re-runs
+    // the same validation the action handler already passed (pure function), and
+    // returns `undefined` when there's nothing to send.
+    const stepsResult = resolveSteps(repoConfig.steps, options.skipRegression, options.regression);
+    // Maps to RalphRunRequest.clientSessionId (hula-server PR #419).
     const clientSessionId = readClientSessionId(issueName);
-    if (clientSessionId) {
-        requestBody.clientSessionId = clientSessionId;
-    }
     // Resolve ephemeral credentials through the shared resolver — the single
     // source of truth for precedence/validation, also used by `execute`.
     // Collect ALL errors before exiting (preserves prior launch behavior).
-    const resolved = resolveEphemeralCredentials(options, config);
+    const resolved = resolveEphemeralCredentials(options, repoConfig);
     let anthropicApiKey = resolved.anthropicApiKey;
     const credentialErrors = resolved.errors;
     if (credentialErrors.length > 0) {
@@ -596,20 +769,26 @@ conflictModeOverride) {
             if (!pasted) {
                 // Empty / cancelled → the original resolver error, then exit.
                 credentialErrors.forEach((msg) => console.error(chalk.red(msg)));
+                if (isGroup)
+                    return { ok: false, message: credentialErrors.join('; ') };
                 process.exit(1);
             }
             if (!pasted.startsWith('sk-ant-oat')) {
                 // Wrong prefix → the existing wrong-prefix error text. One attempt only.
-                console.error(chalk.red('Anthropic credential must be an OAuth token (starts with sk-ant-oat01-…). Standard API keys (sk-ant-api03-…) are not supported — the container requires CLAUDE_CODE_OAUTH_TOKEN.'));
+                const wrongPrefixMsg = 'Anthropic credential must be an OAuth token (starts with sk-ant-oat01-…). Standard API keys (sk-ant-api03-…) are not supported — the container requires CLAUDE_CODE_OAUTH_TOKEN.';
+                console.error(chalk.red(wrongPrefixMsg));
+                if (isGroup)
+                    return { ok: false, message: wrongPrefixMsg };
                 process.exit(1);
             }
             // Valid: use it for this launch and persist it to the config file. A
             // persistence failure must NOT abort a valid launch — warn and continue
-            // with the in-memory key.
+            // with the in-memory key. In group mode the token is written to the
+            // member repo's own config file (repoRoot); in single mode to the git root.
             anthropicApiKey = pasted;
             try {
-                const gitRoot = await findGitRoot();
-                const configFilePath = path.join(gitRoot, '.hublaunch', 'hublaunch.config.js');
+                const configDir = isGroup ? repoRoot : await findGitRoot();
+                const configFilePath = path.join(configDir, '.hublaunch', 'hublaunch.config.js');
                 const original = readFileSync(configFilePath, 'utf-8');
                 const updated = upsertAnthropicApiKey(original, pasted);
                 writeFileSync(configFilePath, updated, { mode: 0o600 });
@@ -621,56 +800,59 @@ conflictModeOverride) {
         }
         else {
             credentialErrors.forEach((msg) => console.error(chalk.red(msg)));
+            if (isGroup)
+                return { ok: false, message: credentialErrors.join('; ') };
             process.exit(1);
         }
     }
-    requestBody.anthropicApiKey = anthropicApiKey;
-    const cpuRaw = options.containerCpu ?? config.containerResources?.cpu;
-    const memRaw = options.containerMemory ?? config.containerResources?.memory;
-    const diskRaw = options.containerDisk ?? config.containerResources?.disk;
+    // Resolve container resources (validate ranges, mode-aware failure).
+    const cpuRaw = options.containerCpu ?? repoConfig.containerResources?.cpu;
+    const memRaw = options.containerMemory ?? repoConfig.containerResources?.memory;
+    const diskRaw = options.containerDisk ?? repoConfig.containerResources?.disk;
+    let containerResources;
     if (cpuRaw !== undefined || memRaw !== undefined || diskRaw !== undefined) {
         const cpu = cpuRaw ?? DEFAULT_CONTAINER_RESOURCES.cpu;
         const memory = memRaw ?? DEFAULT_CONTAINER_RESOURCES.memory;
         const disk = diskRaw ?? DEFAULT_CONTAINER_RESOURCES.disk;
         if (!Number.isInteger(cpu) || cpu < 1 || cpu > 32) {
             logger.error('containerResources.cpu must be an integer between 1 and 32');
+            if (isGroup)
+                return { ok: false, message: 'containerResources.cpu must be an integer between 1 and 32' };
             process.exit(1);
         }
         if (!Number.isInteger(memory) || memory < 1 || memory > 128) {
             logger.error('containerResources.memory must be an integer between 1 and 128 GiB');
+            if (isGroup)
+                return { ok: false, message: 'containerResources.memory must be an integer between 1 and 128 GiB' };
             process.exit(1);
         }
         if (!Number.isInteger(disk) || disk < 5 || disk > 200) {
             logger.error('containerResources.disk must be an integer between 5 and 200 GiB');
+            if (isGroup)
+                return { ok: false, message: 'containerResources.disk must be an integer between 5 and 200 GiB' };
             process.exit(1);
         }
-        requestBody.containerResources = { cpu, memory, disk };
+        containerResources = { cpu, memory, disk };
         logger.log(`  Container Resources: cpu=${cpu} memory=${memory}GiB disk=${disk}GiB`);
     }
-    if (updateNotificationUrl) {
-        requestBody.updateNotificationUrl = updateNotificationUrl;
-    }
-    if (updateNotificationNameTag) {
-        requestBody.updateNotificationNameTag = updateNotificationNameTag;
-    }
-    const tokenData = await loadGitHubToken();
-    const githubToken = tokenData?.access_token || process.env.GITHUB_TOKEN;
-    if (githubToken) {
-        requestBody.githubToken = githubToken;
-    }
-    // Collect environment variables if configured. Read from the project's .env,
+    // Resolve the GitHub token: shared (group mode) or loaded (single mode).
+    const githubToken = ctx.skipTokenLoad
+        ? ctx.githubToken
+        : (await loadGitHubToken())?.access_token || process.env.GITHUB_TOKEN;
+    // Collect environment variables if configured. Read from the repo's .env,
     // validate against the reserved blocklist, and confirm presence — failing fast
     // with a clear message before the job is submitted.
-    if (config.envVars) {
+    let envVars;
+    if (repoConfig.envVars) {
         logger.info('Collecting environment variables for container...');
         try {
             // Expand "all" to the actual list of non-reserved variables from .env.
-            let varsToCollect = Array.isArray(config.envVars)
-                ? config.envVars
+            let varsToCollect = Array.isArray(repoConfig.envVars)
+                ? repoConfig.envVars
                 : [];
-            if (config.envVars === 'all') {
+            if (repoConfig.envVars === 'all') {
                 // Read .env and get all non-reserved variables
-                const envPath = join(process.cwd(), '.env');
+                const envPath = join(repoRoot, '.env');
                 if (!existsSync(envPath)) {
                     throw new Error(`Cannot read environment variables: .env file not found at ${envPath}\n` +
                         `Config specifies envVars: "all", but .env does not exist`);
@@ -686,22 +868,53 @@ conflictModeOverride) {
             // Validate and collect
             if (varsToCollect.length > 0) {
                 validateNoReservedVars(varsToCollect);
-                const envVars = readAndFilterEnvVars(process.cwd(), varsToCollect);
-                if (Object.keys(envVars).length > 0) {
-                    requestBody.envVars = envVars;
-                    logger.log(`  ✓ ${Object.keys(envVars).length} variable(s) collected`);
+                const collected = readAndFilterEnvVars(repoRoot, varsToCollect);
+                if (Object.keys(collected).length > 0) {
+                    envVars = collected;
+                    logger.log(`  ✓ ${Object.keys(collected).length} variable(s) collected`);
                 }
             }
         }
         catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
             logger.error('Failed to collect environment variables:');
-            logger.error(error instanceof Error ? error.message : String(error));
+            logger.error(msg);
+            if (isGroup)
+                return { ok: false, message: `Failed to collect environment variables: ${msg}` };
             process.exit(1);
         }
     }
-    // Pre-flight credential validation
+    // Pre-flight credential validation (skipped in group mode where each distinct
+    // Anthropic key was validated once before the fan-out loop).
     // anthropicApiKey is guaranteed non-null here — missing key exits above
-    await validateLaunchCredentials(anthropicApiKey, githubToken);
+    if (!ctx.credentialsValidated) {
+        await validateLaunchCredentials(anthropicApiKey, githubToken);
+    }
+    // Assemble the request body from the resolved values.
+    const requestBody = buildRalphRunRequestBody({
+        issueName,
+        planPath,
+        repositoryId,
+        duration: options.duration,
+        launchPath: options.launch,
+        worktree: options.worktree,
+        resume: options.resume,
+        fix: options.fix,
+        regression: options.regression,
+        steps: stepsResult.steps,
+        test: options.test,
+        conflictMode,
+        groupId: ctx.groupId,
+        verbose: options.verbose,
+        handoff: options.handoff,
+        clientSessionId: clientSessionId ?? undefined,
+        anthropicApiKey: anthropicApiKey,
+        containerResources,
+        updateNotificationUrl,
+        updateNotificationNameTag,
+        githubToken,
+        envVars,
+    });
     try {
         const response = await axios.post(endpoint, requestBody, {
             headers: {
@@ -731,30 +944,503 @@ conflictModeOverride) {
             }
             logger.blank();
             // Clean up local plan file — it's now on origin/main and submitted to server
-            const planService = new PlanService(config.planPath);
-            planService.deletePlan(planPath);
-        }
-        else {
-            logger.error(response.data.error || 'Unknown error occurred');
-            process.exit(1);
+            const planService = new PlanService(repoConfig.planPath);
+            planService.deletePlan(isAbsolute(planPath) ? planPath : join(repoRoot, planPath));
+            return { ok: true, planId: response.data.planId };
         }
+        logger.error(response.data.error || 'Unknown error occurred');
+        if (isGroup)
+            return { ok: false, message: response.data.error || 'Unknown error occurred' };
+        process.exit(1);
     }
     catch (error) {
         // A 409 on the default `reject` path means a task is already running for this
-        // tracking name. Offer recovery options interactively (or, when scripted,
-        // print the server message and exit). Skip this whenever a conflictMode is
-        // already in play — that request cannot produce a reject 409 and must not
-        // re-enter the prompt (loop guard).
+        // tracking name. Skip this whenever a conflictMode is already in play — that
+        // request cannot produce a reject 409 and must not re-enter the prompt.
         if (!conflictMode &&
             axios.isAxiosError(error) &&
             error.response?.status === 409) {
-            await handleReject409(error, config, issueName, planPath, options);
-            return;
+            if (ctx.interactive409) {
+                // Single mode: offer recovery options interactively (or, when scripted,
+                // print the server message and exit). The resolver drives the flow.
+                await handleReject409(error, repoConfig, issueName, planPath, options);
+                return { ok: true };
+            }
+            // Group mode: record the failure with the server message plus a hint to
+            // re-run with --kill-and-relaunch. Never enters the interactive resolver.
+            const data = (error.response?.data ?? {});
+            const serverMessage = data.error || `A task is already running for '${issueName}'.`;
+            return {
+                ok: false,
+                status: 409,
+                message: `${serverMessage} (re-run with --kill-and-relaunch to force)`,
+            };
+        }
+        if (isGroup) {
+            const described = describeLaunchAxiosError(error, serverUrl, issueName, planPath);
+            return { ok: false, status: described.status, message: described.message };
         }
         handleLaunchAxiosError(error, serverUrl, issueName, planPath);
         process.exit(1);
     }
 }
+/**
+ * Fan-out launch (`hula launch <issue> --folder <path>`). Discovers every
+ * initialized repo under `<path>`, resolves each repo's plan, confirms the
+ * roster, then launches each repo with its own config/key plus one shared
+ * generated (or `--group-id`-supplied) groupId. Continues past per-repo
+ * failures and prints a retry command carrying `--group-id`.
+ */
+async function executeGroupLaunch(_config, issueName, options) {
+    const service = new GroupLaunchService();
+    const folder = path.resolve(options.folder);
+    if (!existsSync(folder)) {
+        logger.error(`Folder not found: ${folder}`);
+        process.exit(1);
+    }
+    const { repos, skipped, folderIsRepo } = service.discoverRepos(folder);
+    logger.section('Group Launch');
+    for (const s of skipped) {
+        logger.log(`  skipped ${s.name} (${s.reason})`);
+    }
+    if (repos.length === 0) {
+        if (folderIsRepo) {
+            logger.error(`${folder} looks like a repository itself; --folder expects the parent folder that contains your repos`);
+        }
+        else {
+            logger.error(`No initialized repos found directly under ${folder}`);
+            logger.info('Each repo needs a .git entry and a .hublaunch config (run hula init + hula login in it).');
+        }
+        process.exit(1);
+    }
+    if (repos.length === 1) {
+        logger.warning('only one repo found — this launches a single-repo group');
+    }
+    // Resolve or accept the group id (already format-validated in the handler).
+    const groupId = options.groupId ?? service.generateGroupId(issueName);
+    // Validate --plan override repo names and reject path-traversal paths.
+    const overrides = options.plan ?? {};
+    const repoNames = new Set(repos.map((r) => r.name));
+    for (const [name, overridePath] of Object.entries(overrides)) {
+        if (!repoNames.has(name)) {
+            logger.error(`Unknown repo in --plan override: "${name}". Discovered repos: ${[...repoNames].join(', ')}`);
+            process.exit(1);
+        }
+        if (overridePath.includes('..')) {
+            logger.error(`Invalid --plan path for "${name}" (path traversal not allowed): ${overridePath}`);
+            process.exit(1);
+        }
+    }
+    const isTty = Boolean(process.stdout.isTTY);
+    // `--yes` opts a non-TTY caller (the /hula-launch skill runs this CLI as a
+    // piped subprocess) into the same auto-resolve + roster flow a TTY gets,
+    // skipping the interactive confirmation. Without it, non-TTY still requires
+    // explicit --plan coverage (never guess silently in CI).
+    const assumeYes = Boolean(options.yes);
+    const canAutoResolve = isTty || assumeYes;
+    // Load each repo's config INDEPENDENTLY (never the cached singleton), resolve
+    // its project, and resolve its plan (override → auto-resolve, disabled non-TTY
+    // unless --yes).
+    const entries = [];
+    for (const repo of repos) {
+        const repoConfig = await new ConfigLoader(repo.path).load();
+        const project = await resolveProject(repoConfig, undefined, repo.path);
+        let loginError;
+        const hasKey = Boolean(options.apiKey) ||
+            Boolean(repoConfig.hulaApiKey) ||
+            Boolean(process.env.HULA_API_KEY);
+        if (!hasKey) {
+            loginError = `NOT LOGGED IN (run hula login in ${repo.path})`;
+        }
+        let planPath;
+        if (overrides[repo.name]) {
+            planPath = overrides[repo.name];
+        }
+        else if (!canAutoResolve) {
+            // Non-TTY without --yes: never guess — require an explicit --plan override.
+            planPath = null;
+        }
+        else {
+            planPath = service.resolvePlan(repo, repoConfig, issueName);
+        }
+        entries.push({ repo, repoConfig, project, planPath, loginError });
+    }
+    // Duplicate project detection: two members with the same repositoryId would
+    // overwrite each other server-side ("latest launch wins"). Fail before launch.
+    const projectToRepos = new Map();
+    for (const e of entries) {
+        projectToRepos.set(e.project, [
+            ...(projectToRepos.get(e.project) ?? []),
+            e.repo.name,
+        ]);
+    }
+    for (const [project, names] of projectToRepos) {
+        if (names.length > 1) {
+            logger.error(`Duplicate project ${project} across discovered repos: ${names.join(', ')}. ` +
+                `Each member must be a distinct repository.`);
+            process.exit(1);
+        }
+    }
+    // Non-TTY coverage: without --yes, every repo must be covered by a --plan
+    // override (a piped/CI caller must opt in before the CLI guesses plans).
+    if (!canAutoResolve) {
+        const uncovered = entries
+            .filter((e) => !overrides[e.repo.name])
+            .map((e) => e.repo.name);
+        if (uncovered.length > 0) {
+            logger.error(`Non-interactive run requires a --plan <repo>=<path> override for every repo (or pass --yes to auto-resolve). Uncovered: ${uncovered.join(', ')}`);
+            process.exit(1);
+        }
+    }
+    // Print the roster and gate on any repo that can't launch.
+    logger.blank();
+    logger.info(`Feature group: ${groupId}`);
+    let blocked = false;
+    for (const e of entries) {
+        let planLabel;
+        if (e.loginError) {
+            planLabel = e.loginError;
+            blocked = true;
+        }
+        else if (!e.planPath) {
+            planLabel = 'NO PLAN FOUND';
+            blocked = true;
+        }
+        else {
+            planLabel = e.planPath;
+        }
+        logger.log(`  ${e.repo.name}  →  ${planLabel}`);
+    }
+    if (blocked) {
+        logger.blank();
+        logger.error('Cannot launch: every repo needs an API key and a resolvable plan.');
+        logger.info('Supply a plan with --plan <repo>=<path>, run hula login in the repo, or remove it from the folder.');
+        process.exit(1);
+    }
+    // Single interactive confirmation before any network launch (TTY only;
+    // --yes skips it — the roster above stays in the output as the record).
+    if (isTty && !assumeYes) {
+        const { proceed } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'proceed',
+                message: `Launch these ${entries.length} repos as group ${groupId}?`,
+                default: true,
+            },
+        ]);
+        if (!proceed) {
+            logger.info('Cancelled — no launches sent.');
+            process.exit(0);
+        }
+    }
+    // ── Shared-once work ──────────────────────────────────────────────────
+    // Pro-tier check with the first repo's key.
+    const first = entries[0];
+    const proServerUrl = options.url || first.repoConfig.hulaProjectUrl || HULA_PROJECT_URL;
+    const proApiKey = options.apiKey || first.repoConfig.hulaApiKey || process.env.HULA_API_KEY;
+    if (proApiKey) {
+        const isPro = await verifyProTier(first.repoConfig, proServerUrl, proApiKey, first.repo.path);
+        if (!isPro)
+            process.exit(1);
+    }
+    // GitHub token once (user-level).
+    const tokenData = await loadGitHubToken();
+    const githubToken = tokenData?.access_token || process.env.GITHUB_TOKEN;
+    // Validate each DISTINCT resolvable Anthropic key once.
+    const validatedKeys = new Set();
+    for (const e of entries) {
+        const key = resolveEphemeralCredentials(options, e.repoConfig).anthropicApiKey;
+        if (key && !validatedKeys.has(key)) {
+            validatedKeys.add(key);
+            await validateLaunchCredentials(key, githubToken);
+        }
+    }
+    // ── Sequential fan-out (continue on failure) ──────────────────────────
+    const results = [];
+    const successfulRepos = [];
+    for (const e of entries) {
+        logger.section(`Launch: ${e.repo.name}`);
+        const result = await launchSingleRepo(e.repoConfig, e.repo.path, issueName, e.planPath, options, {
+            mode: 'group',
+            interactive409: false,
+            groupId,
+            repositoryId: e.project,
+            proTierVerified: true,
+            credentialsValidated: true,
+            skipTokenLoad: true,
+            githubToken,
+        });
+        results.push({ repo: e.repo, project: e.project, planPath: e.planPath, result });
+        if (result.ok) {
+            successfulRepos.push(e.repo);
+        }
+        else {
+            logger.error(`✗ ${e.repo.name}: ${result.message ?? 'launch failed'}`);
+        }
+    }
+    // Record the group locally in every successful member (best-effort).
+    if (successfulRepos.length > 0) {
+        const recordRepos = successfulRepos.map((r) => {
+            const e = entries.find((x) => x.repo.path === r.path);
+            return { name: r.name, path: r.path, project: e.project };
+        });
+        const record = {
+            groupId,
+            issueName,
+            createdAt: new Date().toISOString(),
+            folder,
+            repos: recordRepos,
+        };
+        service.recordGroup(successfulRepos, record);
+    }
+    // ── Summary ───────────────────────────────────────────────────────────
+    logger.section('Group Launch Summary');
+    logger.log(`  Group: ${groupId}`);
+    for (const r of results) {
+        if (r.result.ok) {
+            logger.log(`  ✓ ${r.repo.name}${r.result.planId ? `  (plan ${r.result.planId})` : ''}`);
+        }
+        else {
+            logger.log(`  ✗ ${r.repo.name}  ${r.result.message ?? 'launch failed'}`);
+        }
+    }
+    const failures = results.filter((r) => !r.result.ok);
+    if (failures.length > 0) {
+        logger.blank();
+        logger.info('Retry the whole group (already-successful members may 409):');
+        logger.info(`  hula launch ${issueName} --folder "${options.folder}" --group-id ${groupId}`);
+        logger.info('Or retry a single failed repo surgically:');
+        for (const f of failures) {
+            logger.info(`  cd ${f.repo.path} && hula launch ${issueName} ${f.planPath} --group-id ${groupId}`);
+        }
+        process.exit(1);
+    }
+    logger.blank();
+    logger.success(`Launched ${results.length} repos as group ${groupId}`);
+    logger.info(`View combined status: hula launch --show-group ${groupId}`);
+}
+/**
+ * Cancel-only fan-out (`hula launch <issue> --folder <path> --kill`). Stops the
+ * in-flight task in every member repo using each repo's own API key. Continues
+ * past per-repo failures and exits non-zero when any cancel failed.
+ */
+async function executeGroupKill(_config, issueName, options) {
+    const service = new GroupLaunchService();
+    const folder = path.resolve(options.folder);
+    if (!existsSync(folder)) {
+        logger.error(`Folder not found: ${folder}`);
+        process.exit(1);
+    }
+    const { repos, skipped, folderIsRepo } = service.discoverRepos(folder);
+    logger.section('Group Cancel');
+    for (const s of skipped) {
+        logger.log(`  skipped ${s.name} (${s.reason})`);
+    }
+    if (repos.length === 0) {
+        if (folderIsRepo) {
+            logger.error(`${folder} looks like a repository itself; --folder expects the parent folder that contains your repos`);
+        }
+        else {
+            logger.error(`No initialized repos found directly under ${folder}`);
+        }
+        process.exit(1);
+    }
+    const entries = [];
+    for (const repo of repos) {
+        const repoConfig = await new ConfigLoader(repo.path).load();
+        const project = await resolveProject(repoConfig, undefined, repo.path);
+        entries.push({ repo, repoConfig, project });
+    }
+    // Shared Pro-tier check with the first repo's key.
+    const first = entries[0];
+    const proServerUrl = options.url || first.repoConfig.hulaProjectUrl || HULA_PROJECT_URL;
+    const proApiKey = options.apiKey || first.repoConfig.hulaApiKey || process.env.HULA_API_KEY;
+    if (proApiKey) {
+        const isPro = await verifyProTier(first.repoConfig, proServerUrl, proApiKey, first.repo.path);
+        if (!isPro)
+            process.exit(1);
+    }
+    const results = [];
+    for (const e of entries) {
+        logger.section(`Cancel: ${e.repo.name}`);
+        const result = await killSingleRepo(e.repoConfig, e.repo.path, issueName, options, {
+            repositoryId: e.project,
+            proTierVerified: true,
+        });
+        results.push({ repo: e.repo, result });
+        if (!result.ok) {
+            logger.error(`✗ ${e.repo.name}: ${result.message ?? 'cancel failed'}`);
+        }
+    }
+    logger.section('Group Cancel Summary');
+    for (const r of results) {
+        logger.log(`  ${r.result.ok ? '✓' : '✗'} ${r.repo.name}`);
+    }
+    if (results.some((r) => !r.result.ok)) {
+        process.exit(1);
+    }
+}
+/**
+ * Cancel the in-flight task for one repo (per-repo helper for the `--kill
+ * --folder` fan-out). Mirrors {@link executeKill} but returns a
+ * {@link RepoLaunchResult} instead of exiting, and skips the shared Pro check.
+ */
+async function killSingleRepo(repoConfig, repoRoot, issueName, options, ctx) {
+    const serverUrl = options.url || repoConfig.hulaProjectUrl || HULA_PROJECT_URL;
+    const apiKey = options.apiKey || repoConfig.hulaApiKey || process.env.HULA_API_KEY;
+    if (!apiKey) {
+        return { ok: false, message: 'No API key configured' };
+    }
+    if (!ctx.proTierVerified) {
+        const isPro = await verifyProTier(repoConfig, serverUrl, apiKey);
+        if (!isPro)
+            return { ok: false, message: 'Not on the Pro tier' };
+    }
+    const repositoryId = ctx.repositoryId ?? (await resolveProject(repoConfig, undefined, repoRoot));
+    const endpoint = `${serverUrl.replace(/\/$/, '')}/api/v1/ralph-run`;
+    const requestBody = buildKillRequestBody(issueName, repositoryId);
+    logger.info('Stopping in-flight task...');
+    logger.log(`  Issue Name: ${issueName}`);
+    logger.log(`  Server: ${serverUrl}`);
+    logger.blank();
+    try {
+        const response = await axios.post(endpoint, requestBody, {
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            timeout: 30000,
+        });
+        const data = response.data;
+        if (data.killed) {
+            logger.success(data.message || `Cancelled '${issueName}'`);
+        }
+        else {
+            logger.info(data.message || `No active task to cancel for '${issueName}'`);
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        const described = describeLaunchAxiosError(error, serverUrl, issueName, undefined);
+        logger.error(described.message);
+        return { ok: false, status: described.status, message: described.message };
+    }
+}
+/**
+ * Render combined status for a feature group (`hula launch --show-group [id]`).
+ * The id is explicit (string) or resolved from the newest local group record
+ * (bare flag → `true`). Prints a `completed/total` header and one line per plan.
+ */
+async function showGroupStatus(config, groupIdOrTrue, options) {
+    const serverUrl = options.url || config.hulaProjectUrl || HULA_PROJECT_URL;
+    const apiKey = options.apiKey || config.hulaApiKey || process.env.HULA_API_KEY;
+    if (!serverUrl || !apiKey) {
+        logger.error('Server URL and API key are required.');
+        logger.info("Run 'hula login' to authenticate with hula-project.");
+        process.exit(1);
+    }
+    // Resolve the group id: an explicit value, else the newest local record.
+    let groupId;
+    if (typeof groupIdOrTrue === 'string') {
+        groupId = groupIdOrTrue;
+    }
+    else {
+        const service = new GroupLaunchService();
+        const repoRoot = await findGitRoot();
+        const latest = service.latestRecordedGroupId(repoRoot);
+        if (!latest) {
+            logger.error('No local group record found in this repo. Pass an id: hula launch --show-group <id>');
+            process.exit(1);
+        }
+        groupId = latest;
+    }
+    const idError = validateGroupId(groupId);
+    if (idError) {
+        logger.error(idError);
+        process.exit(1);
+    }
+    const apiClient = new HulaApiClient({
+        baseUrl: serverUrl.replace(/\/$/, ''),
+        apiKey,
+        timeout: 30000,
+    });
+    try {
+        const data = await apiClient.fetchGroupStatus(groupId);
+        logger.section(`Group ${data.groupId}: ${data.completed}/${data.total} completed`);
+        if (data.plans.length === 0) {
+            logger.log('  (no plans yet)');
+        }
+        for (const plan of data.plans) {
+            const taskStatus = plan.latestTask ? plan.latestTask.status : 'no task';
+            const pr = plan.prUrl
+                ? `${plan.prUrl}${plan.prMerged ? ' (merged)' : ''}`
+                : '—';
+            logger.log(`  ${plan.project.fullName}  ${plan.trackingStatus}  task:${taskStatus}  PR:${pr}  ${plan.updatedAt}`);
+        }
+        logger.blank();
+    }
+    catch (error) {
+        const status = (axios.isAxiosError(error) && error.response?.status) ||
+            (error instanceof ApiError ? error.statusCode : undefined);
+        if (status === 404) {
+            logger.error('Group not found (or you are not a member of any of its projects).');
+            logger.info('The server may not support groups yet (requires hula-server with feature groups).');
+            process.exit(1);
+        }
+        if (error instanceof ApiError) {
+            logger.error(error.message);
+            process.exit(1);
+        }
+        handleApiError(error, serverUrl);
+        process.exit(1);
+    }
+}
+/**
+ * Non-logging sibling of {@link handleLaunchAxiosError}: map a launch/kill error
+ * to a `{ status, message }` pair without printing or throwing. Used by the
+ * `--folder` fan-out to CAPTURE a per-repo failure for the end-of-run summary
+ * instead of logging-and-exiting. Message text mirrors the single-repo handler.
+ */
+function describeLaunchAxiosError(error, serverUrl, issueName, planPath) {
+    if (axios.isAxiosError(error)) {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            switch (status) {
+                case 400:
+                    return { status, message: `Bad request: ${data.error || 'Invalid parameters'}` };
+                case 401:
+                    return { status, message: 'Authentication failed. Your API key may be invalid.' };
+                case 402:
+                    return { status, message: 'You cannot run launch because you are on the free tier.' };
+                case 403:
+                    return {
+                        status,
+                        message: data.error || 'Access denied. You may not be authorized for launch.',
+                    };
+                case 404:
+                    return { status, message: data.error || `Not found: ${planPath ?? issueName}` };
+                case 409:
+                    return { status, message: data.error || `Job already running: ${issueName}` };
+                case 500:
+                    return { status, message: `Server error: ${data.error || 'Internal server error'}` };
+                default:
+                    return {
+                        status,
+                        message: `Request failed with status ${status}: ${data.error || error.message}`,
+                    };
+            }
+        }
+        if (error.code === 'ECONNREFUSED') {
+            return { message: `Cannot connect to server at ${serverUrl}` };
+        }
+        if (error.code === 'ETIMEDOUT' || error.code === 'ECONNABORTED') {
+            return { message: 'Request timed out' };
+        }
+        return { message: `Network error: ${error.message}` };
+    }
+    return { message: error instanceof Error ? error.message : String(error) };
+}
 /**
  * Shared axios error handler for the launch / kill request. Surfaces the server
  * `data.error` for 400/403/404/409 (PR #391 returns specific, actionable
@@ -1070,8 +1756,8 @@ export function handleApiError(error, serverUrl) {
 /**
  * Check if plan is synced to origin/main
  */
-async function checkPlanSyncStatus(config, planPath) {
-    const gitService = new GitService();
+async function checkPlanSyncStatus(config, planPath, repoRoot) {
+    const gitService = new GitService(repoRoot);
     const planService = new PlanService(config.planPath);
     // Fetch latest from origin
     await gitService.fetch('origin', 'main');
@@ -1088,8 +1774,10 @@ async function checkPlanSyncStatus(config, planPath) {
     }
     // Plan is not on any git ref, but a plan freshly created by /hula-plan lives
     // only in the working tree (never committed). Treat that as needing upload
-    // rather than declaring it not found.
-    if (existsSync(planPath)) {
+    // rather than declaring it not found. In folder mode the plan path is
+    // repo-relative, so resolve it against the repo root for the disk check.
+    const planFsPath = isAbsolute(planPath) || !repoRoot ? planPath : join(repoRoot, planPath);
+    if (existsSync(planFsPath)) {
         return { synced: false, location: 'local-main' };
     }
     return { synced: false, location: 'not-found' };