@brimveyn/aimux 1.16.2 → 1.18.1

package/src/cli/commands/tab/wait.ts

@@ -0,0 +1,86 @@
+import type { TabActivity } from '../../../state/types'
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_THIN_ATTACH } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_TIMEOUT, writeNdjson } from '../../output'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+function isTabActivity(value: string): value is TabActivity {
+  return value === 'idle' || value === 'working' || value === 'waiting-input'
+}
+
+export const tabWait: CliCommand = {
+  args: [{ name: 'tabId', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'target activity (idle | working | waiting-input)',
+      kind: 'string',
+      name: 'status',
+    },
+    { description: 'timeout in milliseconds (default 30000)', kind: 'number', name: 'timeout' },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+    const statusFlag = ctx.args.flags.status
+    if (typeof statusFlag !== 'string' || !isTabActivity(statusFlag)) {
+      throw new Error('--status must be one of: idle, working, waiting-input')
+    }
+    const timeoutMs =
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    const attach = await daemon.attach({
+      cols: 0,
+      rows: 0,
+      sessionId: workspace.id,
+      thin: true,
+    })
+
+    // Daemon only emits tabStatus on transitions, so a tab that is already at
+    // the target activity would never produce an event and this command would
+    // sit until timeout. Short-circuit on the activity we got from the attach
+    // replay when it already matches.
+    const currentTab = attach.tabs.find((t) => t.id === tabId)
+    if (!currentTab) {
+      throw new Error(`tab not found: ${tabId}`)
+    }
+    if (currentTab.activity === statusFlag) {
+      writeNdjson({ status: statusFlag, tabId, ts: 0 })
+      return EXIT_OK
+    }
+
+    return new Promise<number>((resolve) => {
+      const start = Date.now()
+      const off = daemon.on('tabStatus', (payload) => {
+        if (payload.tabId !== tabId) return
+        writeNdjson({ status: payload.status, tabId, ts: Date.now() - start })
+        if (payload.status === statusFlag) {
+          off()
+          clearTimeout(timer)
+          resolve(EXIT_OK)
+        }
+      })
+      const timer = setTimeout(() => {
+        off()
+        writeNdjson({ status: 'timeout', tabId, ts: Date.now() - start })
+        resolve(EXIT_TIMEOUT)
+      }, timeoutMs)
+    })
+  },
+  summary: 'Stream tabStatus events until the tab reaches the requested state',
+  verb: 'wait',
+}

package/src/cli/commands/workspace/close.ts

@@ -0,0 +1,32 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_WORKSPACE_LIFECYCLE } from '../../../ipc/protocol'
+import { resolveWorkspace } from '../../client/workspace-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const workspaceClose: CliCommand = {
+  args: [{ name: 'workspace', required: true }],
+  flags: SHARED_FLAGS,
+  group: 'workspace',
+  run: async (ctx) => {
+    const target = ctx.args.positionals[0]
+    if (typeof target !== 'string' || target.length === 0) {
+      throw new Error('target workspace is required (id or name)')
+    }
+    const session = resolveWorkspace(target)
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates workspaceLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    await daemon.expectOk('closeWorkspace', { targetSessionId: session.id })
+    writeJson({ closedSessionId: session.id, name: session.name })
+    return EXIT_OK
+  },
+  summary: 'Close a workspace (via the UI when attached, otherwise the catalog)',
+  verb: 'close',
+}

package/src/cli/commands/workspace/create.ts

@@ -0,0 +1,92 @@
+import { resolve as resolvePath } from 'node:path'
+
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_WORKSPACE_LIFECYCLE } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
+
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000
+
+export const workspaceCreate: CliCommand = {
+  args: [{ name: 'name', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'project path to associate with the workspace',
+      kind: 'string',
+      name: 'project',
+    },
+    {
+      description: 'immediately switch the running UI to the new workspace',
+      kind: 'boolean',
+      name: 'switch',
+    },
+    {
+      description: 'with --switch, wait until the UI confirms the switch completed',
+      kind: 'boolean',
+      name: 'wait',
+    },
+    {
+      description: 'timeout for --wait, in milliseconds (default 30000)',
+      kind: 'number',
+      name: 'timeout',
+    },
+  ],
+  group: 'workspace',
+  run: async (ctx) => {
+    const name = ctx.args.positionals[0]
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('workspace name is required')
+    }
+    const projectRaw =
+      typeof ctx.args.flags.project === 'string' ? ctx.args.flags.project : undefined
+    const projectPath = projectRaw === undefined ? undefined : resolvePath(projectRaw)
+    const doSwitch = ctx.args.flags.switch === true
+    const wait = ctx.args.flags.wait === true
+    const timeoutMs =
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_WAIT_TIMEOUT_MS
+
+    if (wait && !doSwitch) {
+      // Without --switch, the UI never emits an ack event, so there's
+      // nothing meaningful for --wait to wait on.
+      throw new Error('--wait requires --switch (nothing to wait for otherwise)')
+    }
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates workspaceLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    if (!wait) {
+      await daemon.expectOk('createWorkspace', { name, projectPath, switch: doSwitch })
+      writeJson({ name, projectPath, switch: doSwitch })
+      return EXIT_OK
+    }
+
+    // Subscribe BEFORE sending the request. The UI's create+switch path
+    // relays as `workspaceSwitched` once handleCreateSessionEffect has
+    // dispatched load-session. Match on name+projectPath since the CLI
+    // doesn't know the id the UI will assign to the new session.
+    const settled = new Promise<number>((resolve) => {
+      const off = daemon.on('workspaceSwitched', (payload) => {
+        off()
+        clearTimeout(timer)
+        writeJson({ name, projectPath, sessionId: payload.sessionId, switch: doSwitch })
+        resolve(EXIT_OK)
+      })
+      const timer = setTimeout(() => {
+        off()
+        writeJson({ error: 'timed out waiting for workspaceSwitched', name, projectPath })
+        resolve(EXIT_TIMEOUT)
+      }, timeoutMs)
+    })
+
+    await daemon.expectOk('createWorkspace', { name, projectPath, switch: doSwitch })
+    return settled
+  },
+  summary: 'Create a new workspace (via the UI when attached, otherwise the catalog)',
+  verb: 'create',
+}

package/src/cli/commands/workspace/list.ts

@@ -0,0 +1,25 @@
+import type { CliCommand } from '../../registry'
+
+import { listWorkspaces } from '../../client/workspace-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const workspaceList: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'workspace',
+  run: async () => {
+    const sessions = listWorkspaces()
+    writeJson({
+      workspaces: sessions.map((session) => ({
+        id: session.id,
+        lastOpenedAt: session.lastOpenedAt,
+        name: session.name,
+        projectPath: session.projectPath,
+      })),
+    })
+    return EXIT_OK
+  },
+  summary: 'List known workspaces (sessions) in the profile catalog',
+  verb: 'list',
+}

package/src/cli/commands/workspace/show.ts

@@ -0,0 +1,32 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const workspaceShow: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'workspace',
+  run: async (ctx) => {
+    const workspace = ctx.getWorkspace()
+    writeJson({
+      activeWorktreeId: workspace.activeWorktreeId,
+      createdAt: workspace.createdAt,
+      id: workspace.id,
+      lastOpenedAt: workspace.lastOpenedAt,
+      name: workspace.name,
+      projectPath: workspace.projectPath,
+      worktrees:
+        workspace.worktrees?.map((w) => ({
+          branch: w.branch,
+          id: w.id,
+          name: w.name,
+          path: w.path,
+          source: w.source,
+        })) ?? [],
+    })
+    return EXIT_OK
+  },
+  summary: 'Show the active workspace (or the one named via --workspace)',
+  verb: 'show',
+}

package/src/cli/commands/workspace/switch.ts

@@ -0,0 +1,75 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_WORKSPACE_LIFECYCLE } from '../../../ipc/protocol'
+import { resolveWorkspace } from '../../client/workspace-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
+
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000
+
+export const workspaceSwitch: CliCommand = {
+  args: [{ name: 'workspace', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'wait until the UI (or daemon) confirms the switch completed',
+      kind: 'boolean',
+      name: 'wait',
+    },
+    {
+      description: 'timeout for --wait, in milliseconds (default 30000)',
+      kind: 'number',
+      name: 'timeout',
+    },
+  ],
+  group: 'workspace',
+  run: async (ctx) => {
+    const target = ctx.args.positionals[0]
+    if (typeof target !== 'string' || target.length === 0) {
+      throw new Error('target workspace is required (id or name)')
+    }
+    const session = resolveWorkspace(target)
+    const wait = ctx.args.flags.wait === true
+    const timeoutMs =
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_WAIT_TIMEOUT_MS
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates workspaceLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    if (!wait) {
+      await daemon.expectOk('switchWorkspace', { targetSessionId: session.id })
+      writeJson({ name: session.name, targetSessionId: session.id })
+      return EXIT_OK
+    }
+
+    // Subscribe BEFORE sending the request so we don't miss the broadcast for
+    // the no-UI path (the daemon emits `workspaceSwitched` synchronously in
+    // that branch).
+    const settled = new Promise<number>((resolve) => {
+      const off = daemon.on('workspaceSwitched', (payload) => {
+        if (payload.sessionId !== session.id) return
+        off()
+        clearTimeout(timer)
+        writeJson({ name: session.name, targetSessionId: session.id })
+        resolve(EXIT_OK)
+      })
+      const timer = setTimeout(() => {
+        off()
+        writeJson({
+          error: 'timed out waiting for workspaceSwitched',
+          targetSessionId: session.id,
+        })
+        resolve(EXIT_TIMEOUT)
+      }, timeoutMs)
+    })
+
+    await daemon.expectOk('switchWorkspace', { targetSessionId: session.id })
+    return settled
+  },
+  summary: 'Switch the UI (or catalog when headless) to another workspace',
+  verb: 'switch',
+}

package/src/cli/commands/worktree/create.ts

@@ -0,0 +1,113 @@
+import type { WorktreeRecord } from '../../../state/types'
+import type { CliCommand } from '../../registry'
+
+import { createGitWorktree, removeGitWorktree } from '../../../git/worktree'
+import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import { createPrefixedId } from '../../../platform/id'
+import {
+  assertSafeAimuxWorktreePath,
+  ensureAimuxWorktreeRoot,
+  makeWorktreePath,
+} from '../../../platform/worktree-paths'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const worktreeCreate: CliCommand = {
+  args: [],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'display name for the new worktree', kind: 'string', name: 'name' },
+    { description: 'branch name (defaults to aimux/<name>)', kind: 'string', name: 'branch' },
+    { description: 'base ref for the branch (defaults to HEAD)', kind: 'string', name: 'base' },
+  ],
+  group: 'worktree',
+  run: async (ctx) => {
+    const name = ctx.args.flags.name
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('--name is required')
+    }
+    const branch =
+      typeof ctx.args.flags.branch === 'string' ? ctx.args.flags.branch : `aimux/${name}`
+    const base = typeof ctx.args.flags.base === 'string' ? ctx.args.flags.base : 'HEAD'
+
+    const workspace = ctx.getWorkspace()
+    const primary = workspace.worktrees?.find((w) => w.source === 'primary')
+    if (!primary) {
+      throw new Error(
+        `workspace "${workspace.name}" has no primary worktree — set --project when creating it`
+      )
+    }
+
+    // Check the daemon's capability BEFORE mutating disk — otherwise a
+    // capability mismatch would leave a git worktree on disk with no
+    // catalog record to track it.
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
+      throw new Error(
+        'daemon predates worktreeLifecycleEvents capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    const worktreeId = createPrefixedId('worktree')
+    const targetPath = makeWorktreePath({
+      repoRoot: primary.repoRoot,
+      worktreeId,
+      worktreeName: name,
+    })
+    await ensureAimuxWorktreeRoot()
+    await assertSafeAimuxWorktreePath(targetPath)
+
+    await createGitWorktree({
+      baseRef: base,
+      branchName: branch,
+      repoPath: primary.repoRoot,
+      targetPath,
+    })
+
+    const now = new Date().toISOString()
+    const record: WorktreeRecord = {
+      baseRef: base,
+      branch,
+      createdAt: now,
+      createdByAimux: true,
+      id: worktreeId,
+      name,
+      path: targetPath,
+      repoRoot: primary.repoRoot,
+      source: 'aimux-temp',
+      updatedAt: now,
+    }
+
+    try {
+      await daemon.expectOk('addWorktreeRecord', { sessionId: workspace.id, worktree: record })
+    } catch (error) {
+      // Catalog registration failed — roll back the on-disk worktree so
+      // `worktree list` doesn't perpetually surface an orphan. Swallow
+      // rollback errors: report the original failure, which is the real
+      // problem the operator needs to see.
+      try {
+        await removeGitWorktree({
+          force: true,
+          repoPath: primary.repoRoot,
+          targetPath,
+        })
+      } catch {
+        // Best-effort rollback; leave the git-side worktree if it can't be
+        // removed cleanly. `worktree list --workspace` will flag it as
+        // `gitTracked: true, catalog: no` on the next inspection.
+      }
+      throw error
+    }
+
+    writeJson({
+      branch,
+      id: worktreeId,
+      name,
+      path: targetPath,
+      repoRoot: primary.repoRoot,
+    })
+    return EXIT_OK
+  },
+  summary: 'Create a new worktree in the active workspace',
+  verb: 'create',
+}

package/src/cli/commands/worktree/list.ts

@@ -0,0 +1,44 @@
+import type { CliCommand } from '../../registry'
+
+import { listGitWorktrees } from '../../../git/worktree'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const worktreeList: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'worktree',
+  run: async (ctx) => {
+    const workspace = ctx.getWorkspace()
+    const records = workspace.worktrees ?? []
+
+    // Cross-check against git so we can flag catalog entries that git no
+    // longer knows about (prunable / vanished) — otherwise the CLI would
+    // happily report worktrees that don't exist on disk.
+    const primary = records.find((w) => w.source === 'primary')
+    const gitPaths = new Set<string>()
+    if (primary) {
+      for (const w of await listGitWorktrees(primary.repoRoot)) {
+        if (w.prunable !== true) gitPaths.add(w.path)
+      }
+    }
+
+    writeJson({
+      activeWorktreeId: workspace.activeWorktreeId ?? null,
+      workspaceId: workspace.id,
+      worktrees: records.map((w) => ({
+        branch: w.branch,
+        createdByAimux: w.createdByAimux,
+        gitTracked: primary ? gitPaths.has(w.path) : null,
+        id: w.id,
+        name: w.name,
+        path: w.path,
+        repoRoot: w.repoRoot,
+        source: w.source,
+      })),
+    })
+    return EXIT_OK
+  },
+  summary: 'List worktrees for a workspace',
+  verb: 'list',
+}

package/src/cli/commands/worktree/remove.ts

@@ -0,0 +1,59 @@
+import type { CliCommand } from '../../registry'
+
+import { removeGitWorktree } from '../../../git/worktree'
+import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const worktreeRemove: CliCommand = {
+  args: [{ name: 'worktree', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'pass --force to git worktree remove', kind: 'boolean', name: 'force' },
+  ],
+  group: 'worktree',
+  run: async (ctx) => {
+    const target = ctx.args.positionals[0]
+    if (typeof target !== 'string' || target.length === 0) {
+      throw new Error('worktree id or path is required')
+    }
+    const force = ctx.args.flags.force === true
+
+    const workspace = ctx.getWorkspace()
+    const worktree =
+      workspace.worktrees?.find((w) => w.id === target) ??
+      workspace.worktrees?.find((w) => w.path === target)
+    if (!worktree) {
+      const known = workspace.worktrees?.map((w) => w.id).join(', ') ?? '(none)'
+      throw new Error(`unknown worktree: ${target} (known: ${known})`)
+    }
+    if (worktree.source === 'primary') {
+      throw new Error('refusing to remove the primary worktree')
+    }
+
+    const primary = workspace.worktrees?.find((w) => w.source === 'primary')
+    if (!primary) {
+      throw new Error('workspace has no primary worktree — cannot resolve repoRoot for git remove')
+    }
+
+    // Git side first — matches the UI's discipline in side-effects.ts. If
+    // git refuses (dirty, uncommitted changes) the catalog stays intact.
+    await removeGitWorktree({ force, repoPath: primary.repoRoot, targetPath: worktree.path })
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
+      throw new Error(
+        'daemon predates worktreeLifecycleEvents capability — restart aimux to pick up the new daemon'
+      )
+    }
+    await daemon.expectOk('removeWorktreeRecord', {
+      sessionId: workspace.id,
+      worktreeId: worktree.id,
+    })
+
+    writeJson({ id: worktree.id, name: worktree.name, path: worktree.path })
+    return EXIT_OK
+  },
+  summary: 'Remove a worktree from the active workspace',
+  verb: 'remove',
+}

package/src/cli/context.ts

@@ -0,0 +1,16 @@
+import type { SessionRecord } from '../state/types'
+import type { DaemonClient } from './client/daemon-client'
+import type { ParsedArgs } from './flags'
+
+/**
+ * Per-command context handed to `CliCommand.run`. Commands lazily resolve
+ * the workspace + daemon via the helpers on this object so a command that
+ * only reads flags (e.g. `workspace list`) doesn't have to open a socket.
+ */
+export interface CliContext {
+  args: ParsedArgs
+  /** Already-running daemon client, populated on first call to `daemon()`. */
+  getDaemon: () => Promise<DaemonClient>
+  /** Resolved workspace, populated on first call to `workspace()`. */
+  getWorkspace: () => SessionRecord
+}

package/src/cli/flags.ts

@@ -0,0 +1,101 @@
+/**
+ * Minimal flag/positional parser. ~50 lines as the plan calls for — no
+ * external dep. Supports `--flag value`, `--flag=value`, boolean `--flag`,
+ * and `--` to end flag parsing. Unknown flags produce a usage error.
+ */
+
+export interface FlagSpec {
+  name: string
+  kind: 'string' | 'number' | 'boolean'
+  description?: string
+}
+
+export interface ArgSpec {
+  name: string
+  required?: boolean
+}
+
+export interface ParsedArgs {
+  flags: Record<string, string | number | boolean>
+  positionals: string[]
+}
+
+export class CliUsageError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CliUsageError'
+  }
+}
+
+export function parseArgs(
+  argv: string[],
+  flagSpecs: readonly FlagSpec[],
+  argSpecs: readonly ArgSpec[]
+): ParsedArgs {
+  const flagByName = new Map<string, FlagSpec>()
+  for (const spec of flagSpecs) flagByName.set(spec.name, spec)
+
+  const flags: Record<string, string | number | boolean> = {}
+  const positionals: string[] = []
+  let stopFlags = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i] ?? ''
+    if (token === '--') {
+      stopFlags = true
+      continue
+    }
+    if (!stopFlags && token.startsWith('--')) {
+      const eq = token.indexOf('=')
+      const name = eq === -1 ? token.slice(2) : token.slice(2, eq)
+      const spec = flagByName.get(name)
+      if (!spec) {
+        throw new CliUsageError(`unknown flag: --${name}`)
+      }
+      if (spec.kind === 'boolean') {
+        if (eq !== -1) {
+          throw new CliUsageError(`flag --${name} does not take a value`)
+        }
+        flags[name] = true
+        continue
+      }
+      const raw = eq === -1 ? argv[++i] : token.slice(eq + 1)
+      if (raw === undefined) {
+        throw new CliUsageError(`flag --${name} requires a value`)
+      }
+      if (spec.kind === 'number') {
+        const parsed = Number(raw)
+        if (!Number.isFinite(parsed)) {
+          throw new CliUsageError(`flag --${name} must be a number (got: ${raw})`)
+        }
+        flags[name] = parsed
+      } else {
+        flags[name] = raw
+      }
+      continue
+    }
+    positionals.push(token)
+  }
+
+  for (let i = 0; i < argSpecs.length; i++) {
+    const spec = argSpecs[i]
+    if (!spec) continue
+    if (spec.required === true && positionals[i] === undefined) {
+      throw new CliUsageError(`missing required argument: <${spec.name}>`)
+    }
+  }
+
+  return { flags, positionals }
+}
+
+/**
+ * Shared flag set — every command takes these. `--workspace` selects the
+ * target session (by id or name); `--profile` overrides `AIMUX_PROFILE`
+ * before any runtime path is resolved; `--json` is a no-op kept for
+ * consistency with future formats.
+ */
+export const SHARED_FLAGS: readonly FlagSpec[] = [
+  { description: 'workspace id or name', kind: 'string', name: 'workspace' },
+  { description: 'runtime profile override (sets AIMUX_PROFILE)', kind: 'string', name: 'profile' },
+  { description: 'always-on JSON output (kept for consistency)', kind: 'boolean', name: 'json' },
+]