infra-kit 0.1.89 → 0.1.90

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infra-kit",
   "type": "module",
-  "version": "0.1.89",
+  "version": "0.1.90",
   "description": "infra-kit",
   "main": "dist/cli.js",
   "module": "dist/cli.js",
@@ -30,9 +30,9 @@
     "fix": "pnpm run prettier-fix && pnpm run eslint-fix && pnpm run qa"
   },
   "dependencies": {
-    "@inquirer/checkbox": "^5.1.3",
-    "@inquirer/confirm": "^6.0.11",
-    "@inquirer/select": "^5.1.3",
+    "@inquirer/checkbox": "^5.1.4",
+    "@inquirer/confirm": "^6.0.12",
+    "@inquirer/select": "^5.1.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.3",
     "pino": "^10.3.1",

package/src/commands/env-clear/env-clear.ts

@@ -9,35 +9,27 @@ import {
   INFRA_KIT_ENV_CONFIG_VAR,
   INFRA_KIT_ENV_LOADED_AT_VAR,
   INFRA_KIT_ENV_PROJECT_VAR,
+  atomicWriteFileSync,
   getSessionCacheDir,
   parseVarNamesFromEnvFile,
 } from 'src/lib/constants'
-import { logger } from 'src/lib/logger'
 import type { ToolsExecutionResult } from 'src/types'
 
 /**
- * Clear loaded env vars. Prints a file path to stdout that must be sourced to apply. The env-clear shell alias does this automatically.
+ * Clear loaded env vars. Prints a file path to stdout that must be sourced to apply.
+ * The env-clear shell alias does this automatically. Throws when no env is loaded
+ * so CLI callers exit non-zero and MCP callers receive a structured tool error.
  */
 export const envClear = async (): Promise<ToolsExecutionResult> => {
   const cacheDir = getSessionCacheDir()
   const envLoadPath = path.join(cacheDir, ENV_LOAD_FILE)
 
   if (!fs.existsSync(envLoadPath)) {
-    logger.error('No loaded environment found. Run `env-load` first.')
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'No loaded environment found. Run `env-load` first.',
-        },
-      ],
-    }
+    throw new Error('No loaded environment found. Run `env-load` first.')
   }
 
   const varNames = parseVarNamesFromEnvFile(envLoadPath)
 
-  // Build unset script
   const unsetLines = [
     ...varNames.map((v) => {
       return `unset ${v}`
@@ -47,16 +39,16 @@ export const envClear = async (): Promise<ToolsExecutionResult> => {
     `unset ${INFRA_KIT_ENV_LOADED_AT_VAR}`,
   ]
 
-  // Write unset script to cache
   const clearFilePath = path.resolve(cacheDir, ENV_CLEAR_FILE)
 
-  fs.mkdirSync(cacheDir, { recursive: true })
-  fs.writeFileSync(clearFilePath, `${unsetLines.join('\n')}\n`)
+  fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 })
+
+  atomicWriteFileSync(clearFilePath, `${unsetLines.join('\n')}\n`, 0o600)
 
   // REQUIRED
   process.stdout.write(`${clearFilePath}\n`)
 
-  // Remove env load file so env-clear can detect "no env loaded" next time
+  // Remove env load file so the next env-clear call correctly reports "no env loaded".
   fs.unlinkSync(envLoadPath)
 
   const structuredContent = {

package/src/commands/env-list/env-list.ts

@@ -1,17 +1,18 @@
 import { z } from 'zod'
 
-import { validateDopplerCliAndAuth } from 'src/integrations/doppler'
 import { getDopplerProject } from 'src/integrations/doppler/doppler-project'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
 import type { ToolsExecutionResult } from 'src/types'
 
 /**
- * List available Doppler configs for the detected project
+ * List available Doppler configs for the detected project.
+ *
+ * Purely local: reads infra-kit.yml and does not call Doppler. We intentionally
+ * do not run validateDopplerCliAndAuth here — users listing envs often do so
+ * before `doppler login`, and a spurious auth error would be misleading.
  */
 export const envList = async (): Promise<ToolsExecutionResult> => {
-  await validateDopplerCliAndAuth()
-
   const project = await getDopplerProject()
   const { environments } = await getInfraKitConfig()
 
@@ -42,7 +43,7 @@ export const envList = async (): Promise<ToolsExecutionResult> => {
 export const envListMcpTool = {
   name: 'env-list',
   description:
-    'List the environments the project is configured to support. Returns a static list defined in infra-kit constants (not a live fetch from Doppler) plus the Doppler project name auto-detected from the current directory. Read-only.',
+    'List the environments the project is configured to support. Returns the `environments` list declared in infra-kit.yml at the project root (not a live fetch from Doppler) plus the Doppler project name resolved from the same file. Read-only.',
   inputSchema: {},
   outputSchema: {
     project: z.string().describe('Detected Doppler project name'),

package/src/commands/env-load/__tests__/env-load.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+
+import { DOPPLER_MAX_OUTPUT_BYTES, assertDopplerOutputSize, assertValidEnvContent, shellSingleQuote } from '../env-load'
+
+describe('shellSingleQuote', () => {
+  it('wraps plain values in single quotes', () => {
+    expect(shellSingleQuote('dev')).toBe("'dev'")
+  })
+
+  it('escapes embedded single quotes using the posix idiom', () => {
+    expect(shellSingleQuote("it's")).toBe(String.raw`'it'\''s'`)
+  })
+
+  it('handles multiple single quotes', () => {
+    expect(shellSingleQuote("a'b'c")).toBe(String.raw`'a'\''b'\''c'`)
+  })
+
+  it('wraps empty strings as empty single quotes', () => {
+    expect(shellSingleQuote('')).toBe("''")
+  })
+
+  it('passes unicode through unchanged', () => {
+    expect(shellSingleQuote('café')).toBe("'café'")
+  })
+
+  it('does not alter backslashes (single-quoted shell strings treat them literally)', () => {
+    expect(shellSingleQuote(String.raw`a\b`)).toBe(String.raw`'a\b'`)
+  })
+})
+
+describe('assertValidEnvContent', () => {
+  it('throws on empty content', () => {
+    expect(() => {
+      return assertValidEnvContent('')
+    }).toThrow(/empty output/)
+  })
+
+  it('throws on whitespace-only content', () => {
+    expect(() => {
+      return assertValidEnvContent('   \n\n  ')
+    }).toThrow(/empty output/)
+  })
+
+  it('accepts a single KEY=value line', () => {
+    expect(() => {
+      return assertValidEnvContent('FOO=bar')
+    }).not.toThrow()
+  })
+
+  it('accepts multiple KEY=value lines', () => {
+    expect(() => {
+      return assertValidEnvContent('FOO=bar\nBAZ=qux\nQUUX=123')
+    }).not.toThrow()
+  })
+
+  it('ignores `set -a` / `set +a` directives', () => {
+    expect(() => {
+      return assertValidEnvContent('set -a\nFOO=bar\nset +a')
+    }).not.toThrow()
+  })
+
+  it('ignores blank lines between KEY=value lines', () => {
+    expect(() => {
+      return assertValidEnvContent('FOO=bar\n\nBAZ=qux')
+    }).not.toThrow()
+  })
+
+  it('throws when first non-blank line is not KEY=value', () => {
+    expect(() => {
+      return assertValidEnvContent('<html>error</html>\nFOO=bar')
+    }).toThrow(/unexpected output/)
+  })
+
+  it('throws when a later line is garbage (not only first-line validation)', () => {
+    expect(() => {
+      return assertValidEnvContent('FOO=bar\n<html>error</html>')
+    }).toThrow(/unexpected output/)
+  })
+
+  it('throws when a line looks like a shell command rather than an assignment', () => {
+    expect(() => {
+      return assertValidEnvContent('FOO=bar\nunset BAR')
+    }).toThrow(/unexpected output/)
+  })
+
+  it('accepts values containing = characters (connection strings)', () => {
+    expect(() => {
+      return assertValidEnvContent('DB_URL=host=db;user=admin\nFOO=bar')
+    }).not.toThrow()
+  })
+})
+
+describe('assertDopplerOutputSize', () => {
+  it('accepts empty output (shape is validated separately)', () => {
+    expect(() => {
+      return assertDopplerOutputSize('')
+    }).not.toThrow()
+  })
+
+  it('accepts typical-sized output', () => {
+    expect(() => {
+      return assertDopplerOutputSize('FOO=bar\n'.repeat(100))
+    }).not.toThrow()
+  })
+
+  it('accepts output exactly at the cap', () => {
+    const atCap = 'x'.repeat(DOPPLER_MAX_OUTPUT_BYTES)
+
+    expect(() => {
+      return assertDopplerOutputSize(atCap)
+    }).not.toThrow()
+  })
+
+  it('rejects output one byte over the cap', () => {
+    const overCap = 'x'.repeat(DOPPLER_MAX_OUTPUT_BYTES + 1)
+
+    expect(() => {
+      return assertDopplerOutputSize(overCap)
+    }).toThrow(/unexpectedly large output/)
+  })
+
+  it('counts bytes not characters (multi-byte unicode)', () => {
+    // "💥" is 4 bytes in UTF-8; N copies = 4N bytes. Pick N so bytes > cap but chars < cap.
+    const chars = Math.ceil(DOPPLER_MAX_OUTPUT_BYTES / 4) + 1
+    const multiByte = '💥'.repeat(chars)
+
+    expect(multiByte.length).toBeLessThan(DOPPLER_MAX_OUTPUT_BYTES)
+    expect(() => {
+      return assertDopplerOutputSize(multiByte)
+    }).toThrow(/unexpectedly large output/)
+  })
+})

package/src/commands/env-load/env-load.ts

@@ -1,4 +1,5 @@
 import select from '@inquirer/select'
+import { Buffer } from 'node:buffer'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -10,9 +11,11 @@ import { getDopplerProject } from 'src/integrations/doppler/doppler-project'
 import { commandEcho } from 'src/lib/command-echo'
 import {
   ENV_LOAD_FILE,
+  ENV_VAR_LINE_PATTERN,
   INFRA_KIT_ENV_CONFIG_VAR,
   INFRA_KIT_ENV_LOADED_AT_VAR,
   INFRA_KIT_ENV_PROJECT_VAR,
+  atomicWriteFileSync,
   getSessionCacheDir,
 } from 'src/lib/constants'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
@@ -57,37 +60,35 @@ export const envLoad = async (args: EnvLoadArgs): Promise<ToolsExecutionResult>
 
   const project = await getDopplerProject()
 
-  $.quiet = true
-  const result =
-    await $`doppler secrets download --no-file --format env --project ${project} --config ${selectedConfig}`
+  const envContent = await downloadDopplerSecrets(project, selectedConfig)
 
-  $.quiet = false
-  const envContent = result.stdout.trim()
+  assertValidEnvContent(envContent)
 
   // Build env file content in dotenv format
   const loadedAt = new Date().toISOString()
   const envFileLines = [
     'set -a',
     envContent,
-    `${INFRA_KIT_ENV_CONFIG_VAR}=${selectedConfig}`,
-    `${INFRA_KIT_ENV_PROJECT_VAR}=${project}`,
-    `${INFRA_KIT_ENV_LOADED_AT_VAR}=${loadedAt}`,
+    `${INFRA_KIT_ENV_CONFIG_VAR}=${shellSingleQuote(selectedConfig)}`,
+    `${INFRA_KIT_ENV_PROJECT_VAR}=${shellSingleQuote(project)}`,
+    `${INFRA_KIT_ENV_LOADED_AT_VAR}=${shellSingleQuote(loadedAt)}`,
     'set +a',
   ]
 
-  // Write env file to cache
   const cacheDir = getSessionCacheDir()
   const envFilePath = path.resolve(cacheDir, ENV_LOAD_FILE)
 
-  fs.mkdirSync(cacheDir, { recursive: true })
-  fs.writeFileSync(envFilePath, `${envFileLines.join('\n')}\n`)
+  fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 })
+  atomicWriteFileSync(envFilePath, `${envFileLines.join('\n')}\n`, 0o600)
 
   // REQUIRED
   process.stdout.write(`${envFilePath}\n`)
 
-  const varCount = envContent.split('\n').filter((line) => {
-    return line.includes('=')
-  }).length
+  // Logs to stderr (pino → pretty-print), so it doesn't pollute the captured
+  // file path that the shell wrapper reads from stdout.
+  commandEcho.print()
+
+  const varCount = countEnvVarLines(envContent)
 
   const structuredContent = {
     filePath: envFilePath,
@@ -107,6 +108,86 @@ export const envLoad = async (args: EnvLoadArgs): Promise<ToolsExecutionResult>
   }
 }
 
+/**
+ * Cap the Doppler stdout we're willing to accept. A well-formed env bundle is
+ * O(10 KB); megabytes would indicate a service regression or the wrong stream
+ * being captured, and we don't want to write that to disk or source it.
+ */
+export const DOPPLER_MAX_OUTPUT_BYTES = 1024 * 1024
+
+/**
+ * Hard upper bound for the Doppler subprocess. Well under zx's default so a
+ * hung call surfaces quickly instead of blocking an interactive shell or an
+ * MCP tool handler.
+ */
+const DOPPLER_DOWNLOAD_TIMEOUT_MS = 30_000
+
+const downloadDopplerSecrets = async (project: string, config: string): Promise<string> => {
+  const prevQuiet = $.quiet
+
+  $.quiet = true
+  try {
+    const result =
+      await $`doppler secrets download --no-file --format env --project ${project} --config ${config}`.timeout(
+        DOPPLER_DOWNLOAD_TIMEOUT_MS,
+      )
+
+    assertDopplerOutputSize(result.stdout)
+
+    return result.stdout.trim()
+  } finally {
+    $.quiet = prevQuiet
+  }
+}
+
+export const assertDopplerOutputSize = (stdout: string): void => {
+  const bytes = Buffer.byteLength(stdout, 'utf-8')
+
+  if (bytes > DOPPLER_MAX_OUTPUT_BYTES) {
+    throw new Error(
+      `doppler returned unexpectedly large output (${bytes} bytes > ${DOPPLER_MAX_OUTPUT_BYTES}) — refusing to write to disk`,
+    )
+  }
+}
+
+const countEnvVarLines = (content: string): number => {
+  return content.split('\n').filter((line) => {
+    return ENV_VAR_LINE_PATTERN.test(line)
+  }).length
+}
+
+const SHELL_DIRECTIVE_LINES = new Set(['set -a', 'set +a'])
+
+export const shellSingleQuote = (value: string): string => {
+  const escaped = value.replaceAll("'", "'\\''")
+
+  return `'${escaped}'`
+}
+
+/**
+ * Guard against Doppler returning non-env output (auth warnings on stdout,
+ * partial downloads, HTML error pages, etc.). Every non-blank, non-directive
+ * line must match KEY=VALUE — skipping directives keeps future format tweaks
+ * cheap without loosening the check.
+ */
+export const assertValidEnvContent = (content: string): void => {
+  if (content.trim().length === 0) {
+    throw new Error('doppler returned empty output for env-load')
+  }
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+
+    if (trimmed.length === 0 || SHELL_DIRECTIVE_LINES.has(trimmed)) continue
+
+    if (!ENV_VAR_LINE_PATTERN.test(trimmed)) {
+      throw new Error(
+        `doppler returned unexpected output for env-load (expected KEY=value lines, got: ${JSON.stringify(trimmed.slice(0, 80))})`,
+      )
+    }
+  }
+}
+
 // MCP Tool Registration
 export const envLoadMcpTool = {
   name: 'env-load',

package/src/commands/env-status/env-status.ts

@@ -51,6 +51,14 @@ export const envStatus = async (): Promise<ToolsExecutionResult> => {
     logger.info(
       `  ${sessionConfig}: ${sessionLoadedCount} of ${sessionTotalCount} vars loaded (project: ${sessionProject}, loadedAt: ${loadedAtDisplay}, session: ${sessionId})\n`,
     )
+
+    if (sessionTotalCount > 0 && sessionLoadedCount < sessionTotalCount) {
+      const missing = sessionTotalCount - sessionLoadedCount
+
+      logger.warn(
+        `  ${missing} cached var(s) are not present in the current process — env-load needs to be re-sourced, or vars were unset manually.`,
+      )
+    }
   } else {
     logger.info(`  Session ${sessionId}: no env loaded\n`)
   }

package/src/commands/init/init.ts

@@ -38,7 +38,6 @@ const isBlockLine = (line: string): boolean => {
     line.startsWith('env-status') ||
     line.startsWith('if ') ||
     line.startsWith('  export INFRA_KIT_SESSION') ||
-    line.startsWith('export _INFRA_KIT_LAST_') ||
     line.startsWith('export _INFRA_KIT_') ||
     line.startsWith(': ${_INFRA_KIT_') ||
     line.startsWith('fi') ||
@@ -113,13 +112,15 @@ const buildShellBlock = (): string => {
     // eslint-disable-next-line no-template-curly-in-string
     ': ${_INFRA_KIT_SHELL_STARTED:=${EPOCHSECONDS:-0}}',
     'export _INFRA_KIT_LAST_LOAD_MTIME _INFRA_KIT_LAST_CLEAR_MTIME _INFRA_KIT_SHELL_STARTED',
-    `env-load() { local f; f=$(${runCmd} env-load "$@") && source "$f" && _INFRA_KIT_LAST_LOAD_MTIME=$(zstat +mtime -- "$f" 2>/dev/null || echo 0) && ${runCmd} env-status; }`,
-    `env-clear() { local f; f=$(${runCmd} env-clear) && source "$f" && _INFRA_KIT_LAST_CLEAR_MTIME=$(zstat +mtime -- "$f" 2>/dev/null || echo 0) && ${runCmd} env-status; }`,
+    `env-load() { local f m; f=$(${runCmd} env-load "$@") || return; m=$(zstat +mtime -- "$f" 2>/dev/null || echo 0); _INFRA_KIT_LAST_LOAD_MTIME=$m; source "$f"; ${runCmd} env-status; }`,
+    `env-clear() { local f m; f=$(${runCmd} env-clear) || return; m=$(zstat +mtime -- "$f" 2>/dev/null || echo 0); _INFRA_KIT_LAST_CLEAR_MTIME=$m; source "$f"; ${runCmd} env-status; }`,
     `env-status() { ${runCmd} env-status; }`,
     `alias ik='${runCmd}'`,
     '_infra_kit_autoload() {',
     '  [[ -z "$INFRA_KIT_SESSION" ]] && return',
-    '  local dir="./node_modules/.cache/infra-kit/$INFRA_KIT_SESSION"',
+    // eslint-disable-next-line no-template-curly-in-string
+    '  local cache_root="${XDG_CACHE_HOME:-$HOME/.cache}/infra-kit"',
+    '  local dir="$cache_root/$INFRA_KIT_SESSION"',
     '  local load_file="$dir/env-load.sh"',
     '  local clear_file="$dir/env-clear.sh"',
     '  local mtime',
@@ -142,7 +143,9 @@ const buildShellBlock = (): string => {
     '  fi',
     '}',
     'autoload -Uz add-zsh-hook',
-    'add-zsh-hook precmd _infra_kit_autoload',
+    'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
+    '  add-zsh-hook precmd _infra_kit_autoload',
+    'fi',
     MARKER_END,
   ].join('\n')
 }

package/src/commands/worktrees-add/worktrees-add.ts

@@ -5,10 +5,11 @@ import process from 'node:process'
 import { z } from 'zod'
 import { $ } from 'zx'
 
+import { openCmuxWorkspaceWithLayout } from 'src/integrations/cmux'
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
-import { getCurrentWorktrees, getProjectRoot } from 'src/lib/git-utils'
+import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { logger } from 'src/lib/logger'
 import { detectReleaseType, formatBranchChoices, getJiraDescriptions } from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
@@ -24,6 +25,7 @@ interface WorktreeManagementArgs extends RequiredConfirmedOptionArg {
   versions?: string
   cursor?: boolean
   githubDesktop?: boolean
+  cmux?: boolean
 }
 
 /**
@@ -31,7 +33,7 @@ interface WorktreeManagementArgs extends RequiredConfirmedOptionArg {
  * Creates worktrees for active release branches and removes unused ones
  */
 export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<ToolsExecutionResult> => {
-  const { confirmedCommand, all, versions, cursor, githubDesktop } = options
+  const { confirmedCommand, all, versions, cursor, githubDesktop, cmux } = options
 
   commandEcho.start('worktrees-add')
 
@@ -147,6 +149,18 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
       commandEcho.addOption('--no-github-desktop', true)
     }
 
+    const openInCmux = cmux ?? (await confirm({ message: 'Open created worktrees in cmux?' }))
+
+    if (typeof cmux === 'undefined') {
+      commandEcho.setInteractive()
+    }
+
+    if (openInCmux) {
+      commandEcho.addOption('--cmux', true)
+    } else {
+      commandEcho.addOption('--no-cmux', true)
+    }
+
     const { branchesToCreate } = categorizeWorktrees({
       selectedReleaseBranches,
       currentWorktrees,
@@ -169,6 +183,19 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
       }
     }
 
+    if (openInCmux) {
+      const repoName = await getRepoName()
+
+      for (const branch of createdWorktrees) {
+        const version = branch.replace('release/', '')
+
+        await openCmuxWorkspaceWithLayout({
+          cwd: `${worktreeDir}/${branch}`,
+          title: `${repoName} ${version}`,
+        })
+      }
+    }
+
     commandEcho.print()
 
     const structuredContent = {
@@ -269,7 +296,7 @@ const logResults = (created: string[]): void => {
 export const worktreesAddMcpTool = {
   name: 'worktrees-add',
   description:
-    'Create local git worktrees for release branches under the worktrees directory and run "pnpm install" in each. Mutates the local filesystem. When invoked via MCP, pass either "versions" (comma-separated) or all=true — the branch picker and "open in Cursor / GitHub Desktop" follow-up prompts are unreachable without a TTY, and the CLI confirmation is auto-skipped for MCP calls.',
+    'Create local git worktrees for release branches under the worktrees directory and run "pnpm install" in each. Mutates the local filesystem. When invoked via MCP, pass either "versions" (comma-separated) or all=true — the branch picker and "open in Cursor / GitHub Desktop / cmux" follow-up prompts are unreachable without a TTY, and the CLI confirmation is auto-skipped for MCP calls.',
   inputSchema: {
     all: z
       .boolean()
@@ -295,6 +322,12 @@ export const worktreesAddMcpTool = {
       .describe(
         'Open each created worktree in GitHub Desktop. Defaults to false in MCP mode (the follow-up prompt is not shown).',
       ),
+    cmux: z
+      .boolean()
+      .optional()
+      .describe(
+        'Open each created worktree in a new cmux workspace with a 3-pane layout (left-top, left-bottom, full-height right), all rooted at the worktree directory. Defaults to false in MCP mode (the follow-up prompt is not shown).',
+      ),
   },
   outputSchema: {
     createdWorktrees: z.array(z.string()).describe('List of created git worktree branches'),

package/src/entry/cli.ts

@@ -19,9 +19,25 @@ import { worktreesAdd } from 'src/commands/worktrees-add'
 import { worktreesList } from 'src/commands/worktrees-list'
 import { worktreesRemove } from 'src/commands/worktrees-remove'
 import { worktreesSync } from 'src/commands/worktrees-sync'
+import { logger } from 'src/lib/logger'
 
 const program = new Command()
 
+const runProgram = async (argv?: string[]): Promise<void> => {
+  try {
+    if (argv) {
+      await program.parseAsync(argv)
+    } else {
+      await program.parseAsync()
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+
+    logger.error(message)
+    process.exit(1)
+  }
+}
+
 program
   .command('merge-dev')
   .description('Merge dev branch into every release branch')
@@ -123,6 +139,8 @@ program
   .option('--no-cursor', 'Skip Cursor prompt')
   .option('-g, --github-desktop', 'Open created worktrees in GitHub Desktop')
   .option('--no-github-desktop', 'Skip GitHub Desktop prompt')
+  .option('-m, --cmux', 'Open created worktrees in cmux (3-pane layout)')
+  .option('--no-cmux', 'Skip cmux prompt')
   .action(async (options) => {
     await worktreesAdd({
       confirmedCommand: options.yes,
@@ -130,6 +148,7 @@ program
       versions: options.versions,
       cursor: options.cursor,
       githubDesktop: options.githubDesktop,
+      cmux: options.cmux,
     })
   })
 
@@ -250,7 +269,7 @@ if (process.argv.length <= 2) {
     { output: process.stderr },
   )
 
-  program.parse(['node', 'infra-kit', selected])
+  await runProgram(['node', 'infra-kit', selected])
 } else {
-  program.parse()
+  await runProgram()
 }

package/src/integrations/cmux/index.ts

@@ -0,0 +1 @@
+export { openCmuxWorkspaceWithLayout } from './open-workspace-with-layout'

package/src/integrations/cmux/open-workspace-with-layout.ts

@@ -0,0 +1,41 @@
+import { $ } from 'zx'
+
+interface OpenCmuxWorkspaceArgs {
+  cwd: string
+  title?: string
+}
+
+/**
+ * Opens a new cmux workspace rooted at `cwd` with three panes:
+ *   left-top (primary) | right (full-height)
+ *   left-bottom        |
+ * All panes inherit `cwd` from the workspace.
+ */
+export const openCmuxWorkspaceWithLayout = async (args: OpenCmuxWorkspaceArgs): Promise<void> => {
+  const { cwd, title } = args
+
+  await $`cmux new-workspace --cwd ${cwd}`
+
+  const workspaceRef = (await $`cmux current-workspace`).stdout.trim()
+
+  const surfacesOutput = (await $`cmux list-pane-surfaces --workspace ${workspaceRef}`).stdout
+
+  const leftTopRef = parseFirstSurfaceRef(surfacesOutput)
+
+  await $`cmux new-split right --workspace ${workspaceRef} --surface ${leftTopRef}`
+  await $`cmux new-split down --workspace ${workspaceRef} --surface ${leftTopRef}`
+
+  if (title) {
+    await $`cmux rename-workspace --workspace ${workspaceRef} ${title}`
+  }
+}
+
+const parseFirstSurfaceRef = (output: string): string => {
+  const match = output.match(/surface:\d+/)
+
+  if (!match) {
+    throw new Error('cmux: could not locate initial surface in list-pane-surfaces output')
+  }
+
+  return match[0]
+}