@geekbeer/minion 3.42.3 → 3.49.0

package/docs/api-reference.md

@@ -803,12 +803,29 @@ POST body:
   "priority": "normal",      // low|normal|high|urgent (default: normal)
   "milestone_id": null,
   "parent_task_id": null,    // 指定時は子タスクとして作成。親が既に子の場合 400
+  "sprint_id": null,         // スプリントに含める場合のみ指定
   "assignee_minion_id": null,
   "assignee_user_id": null,  // assignee_minion_id と同時指定不可
-  "due_date": null           // YYYY-MM-DD
+  "due_date": null,          // YYYY-MM-DD
+  "acceptance_criteria": null // [{id?, text, checked?}] または string[] (idは省略時サーバが付与)
 }
 ```
 
+**`acceptance_criteria` の形式:**
+- `null` = 未設定
+- `[{id: uuid, text: string, checked: boolean}, ...]` または `["text", "text", ...]`
+- 既存項目の checked を更新する場合は **id を保持して** PATCH すること(idを省くと新規追加扱い)
+- 配列を渡すとサーバ側で全置換される。既存項目を残したい場合は GET → 部分更新 → PATCH の手順を踏む
+
+**スプリント自動着手 (Definition of Ready):**
+- ボードタスクは `assignee_minion_id == self && status IN ('todo', 'doing') && sprint.status == 'active'` のとき、
+  ミニオンの `board-task-poller` が自動検知し `doing` へ遷移して **専用 tmux セッション (`bt-{taskId8}`) で自走** を起動する (v3.46.0〜)。
+- `doing` 状態のタスクも対象に含むのは前スプリントからの持ち越しを救済するため。同名 tmux セッションが既に生きていれば再起動せずスキップ (二重実行防止)。
+- スプリント開始(`active`遷移)には全タスクで以下が必要:
+  - `assignee_minion_id` が設定されている
+  - `acceptance_criteria` が1件以上ある
+- 自動着手したミニオンは acceptance_criteria を満たしたら `status: 'review'` に遷移する。`done` は基本的に人間の承認後。
+
 ミニオン経由で作成したタスクには `created_by_minion_id` に自身のIDが自動設定される。
 
 PATCH body: 同じフィールドを任意で部分指定。**`status` を変更すると `status_changed_at` がサーバ側で自動更新される**(stalled 検出に使われる)。手動で `status_changed_at` を渡しても無視される。`assignee_minion_id` を set するともう一方の `assignee_user_id` は自動 null、その逆も同じ。
@@ -825,6 +842,61 @@ reorder body:
 
 両 neighbor が null の場合は列の先頭/初期値で挿入される。
 
+#### `[task:UUID]` チケットタグ (HQチャット内専用)
+
+ユーザーがHQチャットでチケットを参照する際、`[task:UUID]` 形式のタグを
+メッセージに埋め込むことができる。HQプロキシがタグを検出してタスク詳細を
+解決し、チャットリクエストの `referenced_tasks` フィールドに同梱して
+ミニオンに送信する。ミニオンは受信時にプロンプト先頭へ「参照チケット」
+ブロックとして注入する(履歴には保存されない)。
+
+ユーザーメッセージ例:
+```
+[task:550e8400-e29b-41d4-a716-446655440000] このチケットの進捗を教えて
+```
+
+Claudeへの注入例:
+```
+[参照チケット — ユーザーがメッセージ内で `[task:UUID]` 形式で参照しているHQボード上のタスク]
+- [task:550e8400-...] チケット名 (status: doing, priority: high) / 説明...
+  詳細/更新: GET|PATCH $HQ_URL/api/minion/projects/<projectId>/tasks/<taskId>
+
+(ユーザーメッセージ本文)
+```
+
+応答内でユーザーへのチケット言及にも同タグを使ってよい(HQ側でチップに描画される)。
+
+### Project Sprints (Agile自動着手)
+
+スプリントはプロジェクトスコープのエンティティで、`planned -> active -> completed` の状態遷移を持つ。
+**1プロジェクトにつき active スプリントは1つだけ** (DB側の partial unique index で強制)。
+
+スプリントが `active` のとき、含まれるタスクのうち以下を満たすものはミニオンの `board-task-poller` (30秒間隔) が
+自動的に検知して着手する:
+- `assignee_minion_id == 自分`
+- `status IN ('todo', 'doing')`
+- `sprint.status == 'active'`
+
+着手時の流れ (v3.46.0〜):
+1. ローカル tmux に `bt-{taskId8}` セッションが既にあればスキップ (二重実行防止 / 持ち越しの再起動防止)
+2. `POST /api/minion/board-tasks/:taskId/claim` で冪等に `doing` に遷移 (`todo→doing` または `doing→doing` でタイムスタンプ更新)
+3. **専用 tmux セッション (`bt-{taskId8}`) で `claude -p` を直接実行**。Linuxはホスト上のtmux、Windowsは WSL 内の tmux。
+   タスクのタイトル/受け入れ要件、project_contexts.content、メンバー一覧がプロンプトに自動注入される。
+4. ミニオンは acceptance_criteria を満たしたら `status: 'review'` に遷移してユーザーレビュー待ちにする。
+
+セッション可視性:
+- Linuxミニオン: `tmux ls | grep '^bt-'` でセッション一覧。WSターミナルからアタッチ可能。
+- Windowsミニオン: `wsl tmux ls | grep '^bt-'` で確認 (or HQ ダッシュボードのターミナル一覧で `wsl-tmux` タイプとして表示)。
+
+ミニオンが自分で参照する用途のためのスプリント API:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/projects/:projectId/sprints` | スプリント一覧 (HQ認証 — ユーザーUI用) |
+
+ミニオンからスプリントを直接作成・遷移させる必要は通常ない (PMロールのユーザーが管理する)。
+状況確認用には標準のタスクAPIで `?sprint_id=<uuid>` を使えば所属タスクが取得できる。
+
 ### Project Milestones
 
 | Method | Endpoint | Description |

package/linux/board-task-runner.js

@@ -0,0 +1,227 @@
+/**
+ * Board Task Runner (Linux)
+ *
+ * Starts a board task in a dedicated detached tmux session so the work is
+ * visible from the WS terminal (`tmux ls` shows `bt-{taskId8}`) and survives
+ * minion restarts. Unlike workflow/routine runners this does not run on a
+ * cron — it is invoked by board-task-poller after a successful claim.
+ *
+ * Session naming: `bt-{taskId.slice(0,8)}`
+ *
+ * Lifecycle:
+ *   1. If a `bt-*` tmux session already exists for this task, return early
+ *      (carry-over case: minion restarted while the task was running, or a
+ *      previous sprint left it alive). The existing session is the authority.
+ *   2. Otherwise spawn `claude -p < kickoff.txt` inside a new tmux session
+ *      with remain-on-exit so the post-completion buffer stays inspectable.
+ *   3. Wait for an exit-code file to appear, then release.
+ */
+
+const { exec } = require('child_process')
+const { promisify } = require('util')
+const fs = require('fs').promises
+const os = require('os')
+const path = require('path')
+const execAsync = promisify(exec)
+
+const { config } = require('../core/config')
+const runningTasks = require('../core/lib/running-tasks')
+const logManager = require('../core/lib/log-manager')
+const { getActivePrimary } = require('../core/llm-plugins/lib/active')
+const { buildBoardTaskInjection } = require('../core/lib/board-task-context')
+
+// 4 hours — board tasks can be long-running but not infinite.
+const TASK_TIMEOUT_MS = 4 * 60 * 60 * 1000
+const POLL_INTERVAL_MS = 5_000
+
+function generateSessionName(taskId) {
+  if (!taskId) throw new Error('taskId is required')
+  return `bt-${String(taskId).substring(0, 8)}`
+}
+
+async function tmuxHasSession(sessionName) {
+  try {
+    await execAsync(`tmux has-session -t "${sessionName}" 2>/dev/null`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function listBoardTaskSessions() {
+  try {
+    const { stdout } = await execAsync(`tmux ls -F '#S' 2>/dev/null`)
+    return stdout
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((s) => s.startsWith('bt-'))
+  } catch {
+    return []
+  }
+}
+
+function buildKickoffPrompt(task, contextData) {
+  const lines = [
+    `[ボードタスク自動着手] [task:${task.id}] ${task.title}`,
+    '',
+    'このボードタスクが自動でアサインされたため、着手を開始してください。',
+    'アクティブスプリント内でステータスを `doing` にしました。',
+    '',
+    '完了したら以下で `review` に遷移してユーザーにレビュー依頼してください:',
+    `  PATCH \$HQ_URL/api/minion/projects/${task.project_id}/tasks/${task.id}`,
+    '  Body: {"status": "review"}',
+    '',
+  ]
+  const injection = buildBoardTaskInjection({
+    type: 'board_task',
+    task,
+    project_id: task.project_id,
+    sprint: contextData.sprint || null,
+    project_context_content: contextData.projectContextContent || null,
+    members: contextData.members || null,
+  })
+  if (injection) {
+    lines.push(injection)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Start (or resume tracking of) a board task tmux session.
+ *
+ * @param {object} params
+ * @param {object} params.task - Claimed task object from HQ.
+ * @param {object} [params.contextData] - { sprint, projectContextContent, members }
+ * @returns {Promise<{ sessionName: string, started: boolean, success: boolean, error?: string }>}
+ */
+async function runBoardTask({ task, contextData = {} }) {
+  if (!task || !task.id) {
+    return { sessionName: null, started: false, success: false, error: 'task is required' }
+  }
+
+  const sessionName = generateSessionName(task.id)
+  const homeDir = config.HOME_DIR
+
+  // Carry-over: a tmux session for this task is already alive. Don't relaunch.
+  if (await tmuxHasSession(sessionName)) {
+    console.log(`[BoardTaskRunner] tmux session ${sessionName} already exists, skipping start`)
+    runningTasks.add({
+      type: 'board_task',
+      session_name: sessionName,
+      board_task_id: task.id,
+      started_at: new Date().toISOString(),
+    })
+    return { sessionName, started: false, success: true }
+  }
+
+  const exitCodeFile = `/tmp/tmux-exit-${sessionName}`
+  const promptFile = path.join(os.tmpdir(), `minion-board-task-prompt-${sessionName}.txt`)
+  const execScript = path.join(os.tmpdir(), `minion-board-task-exec-${sessionName}.sh`)
+
+  console.log(`[BoardTaskRunner] Starting board task ${task.id} (${task.title})`)
+  console.log(`[BoardTaskRunner] tmux session: ${sessionName}`)
+
+  try {
+    await logManager.ensureLogDir()
+    await execAsync(`rm -f "${exitCodeFile}"`)
+
+    const prompt = buildKickoffPrompt(task, contextData)
+    await fs.writeFile(promptFile, prompt, 'utf-8')
+
+    const primary = getActivePrimary()
+    let llmCommand
+    if (primary && typeof primary.buildShellInvocation === 'function') {
+      llmCommand = primary.buildShellInvocation({ promptFile })
+    } else if (config.LLM_COMMAND) {
+      llmCommand = `${config.LLM_COMMAND} < ${promptFile}`
+    } else {
+      throw new Error('No LLM configured. Set a Primary plugin via /api/llm/config or LLM_COMMAND in minion.env')
+    }
+
+    await fs.writeFile(
+      execScript,
+      `#!/bin/bash\n${llmCommand}\necho $? > ${exitCodeFile}\n`,
+      'utf-8',
+    )
+    await execAsync(`chmod +x "${execScript}"`)
+
+    await execAsync(
+      `tmux new-session -d -s "${sessionName}" -x 200 -y 50`,
+      { cwd: homeDir },
+    )
+    await execAsync(`tmux set-option -t "${sessionName}" remain-on-exit on`)
+
+    // Pipe-pane to per-task log file (reuse log-manager naming under board-task-)
+    const logFile = path.join(logManager.LOG_DIR || path.join(homeDir, '.minion', 'logs'), `board-task-${task.id}.log`)
+    try {
+      await execAsync(`tmux pipe-pane -o -t "${sessionName}" "cat >> ${logFile}"`)
+    } catch (err) {
+      console.error(`[BoardTaskRunner] pipe-pane failed: ${err.message}`)
+    }
+
+    await execAsync(
+      `tmux send-keys -t "${sessionName}" "bash ${execScript}" Enter`,
+    )
+
+    runningTasks.add({
+      type: 'board_task',
+      session_name: sessionName,
+      board_task_id: task.id,
+      started_at: new Date().toISOString(),
+    })
+
+    const startTime = Date.now()
+    while (Date.now() - startTime < TASK_TIMEOUT_MS) {
+      try {
+        await fs.access(exitCodeFile)
+        break
+      } catch {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS))
+      }
+    }
+
+    if (Date.now() - startTime >= TASK_TIMEOUT_MS) {
+      console.error(`[BoardTaskRunner] Task ${task.id} timed out after ${TASK_TIMEOUT_MS / 1000}s`)
+      await execAsync(`tmux kill-session -t "${sessionName}" 2>/dev/null || true`)
+      return { sessionName, started: true, success: false, error: 'Execution timeout' }
+    }
+
+    let exitCode = 0
+    try {
+      const { stdout } = await execAsync(`cat "${exitCodeFile}"`)
+      exitCode = parseInt(stdout.trim(), 10) || 0
+      await execAsync(`rm -f "${exitCodeFile}"`)
+    } catch {
+      // Treat as success if exit code can't be read but file existed
+    }
+
+    if (exitCode === 0) {
+      console.log(`[BoardTaskRunner] Task ${task.id} CLI completed`)
+      return { sessionName, started: true, success: true }
+    }
+    console.error(`[BoardTaskRunner] Task ${task.id} CLI exited with code ${exitCode}`)
+    return { sessionName, started: true, success: false, error: `Exit code: ${exitCode}` }
+  } catch (err) {
+    console.error(`[BoardTaskRunner] Task ${task.id} failed: ${err.message}`)
+    return { sessionName, started: true, success: false, error: err.message }
+  } finally {
+    runningTasks.remove(sessionName)
+    try { await fs.unlink(promptFile) } catch {}
+    try { await fs.unlink(execScript) } catch {}
+  }
+}
+
+/**
+ * Check if a board task is currently running (tmux session alive).
+ * Used by the poller to skip tasks already being worked on.
+ */
+async function isBoardTaskRunning(taskId) {
+  return tmuxHasSession(generateSessionName(taskId))
+}
+
+module.exports = {
+  runBoardTask,
+  isBoardTaskRunning,
+  generateSessionName,
+  listBoardTaskSessions,
+}

package/linux/routes/chat.js

@@ -43,7 +43,7 @@ async function chatRoutes(fastify) {
       return { success: false, error: 'Unauthorized' }
     }
 
-    const { message, session_id, context, workspace_id } = request.body || {}
+    const { message, session_id, context, workspace_id, referenced_tasks } = request.body || {}
 
     if (!message || typeof message !== 'string') {
       reply.code(400)
@@ -53,7 +53,9 @@ async function chatRoutes(fastify) {
     const workspaceId = workspace_id || null
 
     // Build prompt — add memory context on new sessions + page context + workspace
-    const prompt = await buildContextPrefix(message, context, session_id, workspaceId)
+    // referenced_tasks is injected into the prompt only (not stored in history)
+    // so the user's chat log keeps just the [task:UUID] tag, not a noisy dump.
+    const prompt = await buildContextPrefix(message, context, session_id, workspaceId, referenced_tasks)
 
     // Store user message
     const currentSessionId = session_id || null
@@ -258,9 +260,27 @@ ${indexed}`
  * On new sessions (no session_id), injects minion memory + recent daily logs.
  * No conversation history injection — Claude CLI handles that via --resume.
  */
-async function buildContextPrefix(message, context, sessionId, workspaceId) {
+async function buildContextPrefix(message, context, sessionId, workspaceId, referencedTasks) {
   const parts = []
 
+  // Resolved [task:UUID] tags from HQ — surface ticket details so Claude can
+  // talk about them without first having to hit the API. Always include when
+  // present (regardless of session state), since tag references can appear in
+  // any turn.
+  if (Array.isArray(referencedTasks) && referencedTasks.length > 0) {
+    parts.push('[参照チケット — ユーザーがメッセージ内で `[task:UUID]` 形式で参照しているHQボード上のタスク]')
+    for (const t of referencedTasks) {
+      if (!t || !t.id) continue
+      const desc = t.description ? ` / ${String(t.description).slice(0, 200).replace(/\s+/g, ' ')}` : ''
+      const due = t.due_date ? ` / 期限: ${t.due_date}` : ''
+      parts.push(
+        `- [task:${t.id}] ${t.title || '(無題)'} (status: ${t.status || '?'}, priority: ${t.priority || '?'}${due})${desc}`,
+        `  詳細/更新: GET|PATCH $HQ_URL/api/minion/projects/${t.project_id}/tasks/${t.id}`,
+      )
+    }
+    parts.push('')
+  }
+
   // Inject workspace context so Claude Code knows which workspace it's operating in
   if (workspaceId) {
     const workspaceStore = require('../../core/stores/workspace-store')
@@ -411,9 +431,9 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  hq fetch project ${context.projectId}`,
             `  hq fetch project-context ${context.projectId}`,
             `タスク・マイルストーン・健康度を扱う場合は以下のAPIを使えます (Bearer 認証必須):`,
-            `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/tasks       # 一覧 (?milestone_id= ?status= ?priority=high,urgent ?assignee_minion_id= ?overdue=true ?q=<substring> 等で絞り込み可。q は日本語OKの部分一致)`,
-            `  POST   \$HQ_URL/api/minion/projects/${context.projectId}/tasks       # 作成 (body: title, description?, status?, priority?, milestone_id?, parent_task_id?, assignee_minion_id?, due_date?)`,
-            `  PATCH  \$HQ_URL/api/minion/projects/${context.projectId}/tasks/<id>  # 更新 (status変更で status_changed_at がサーバ自動更新、priority 変更も可)`,
+            `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/tasks       # 一覧 (?milestone_id= ?sprint_id= ?status= ?priority=high,urgent ?assignee_minion_id= ?overdue=true ?q=<substring> 等で絞り込み可。q は日本語OKの部分一致)`,
+            `  POST   \$HQ_URL/api/minion/projects/${context.projectId}/tasks       # 作成 (body: title, description?, status?, priority?, milestone_id?, sprint_id?, parent_task_id?, assignee_minion_id?, due_date?, acceptance_criteria?)`,
+            `  PATCH  \$HQ_URL/api/minion/projects/${context.projectId}/tasks/<id>  # 更新 (status変更で status_changed_at がサーバ自動更新、acceptance_criteria/sprint_id も更新可。AC更新時は既存idを保持)`,
             `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/milestones  # マイルストーン一覧`,
             `  GET    \$HQ_URL/api/minion/projects/${context.projectId}/health      # 健康度サマリ (overdue/stalled/マイルストーン進捗。progress_pct は leaf タスク基準)`,
             `タスクは5段階Kanban (backlog→todo→doing→review→done)、親子は2階層まで(孫不可)。priority は low|normal|high|urgent (可視化+フィルタ用)。親EPICに milestone_id を付ければ子タスクも進捗に自動反映される。詳細は ~/.minion/docs/api-reference.md の「Project Tasks」「Project Milestones」「Project Health」を参照。`,

package/linux/server.js

@@ -50,6 +50,7 @@ let lastBeatAt = null
 // Linux-specific modules
 const workflowRunner = require('./workflow-runner')
 const routineRunner = require('./routine-runner')
+const boardTaskRunner = require('./board-task-runner')
 const { cleanupTtyd, killStaleTtydProcesses } = require('./routes/terminal')
 const { startTerminalProxy, stopTerminalProxy } = require('./terminal-proxy')
 
@@ -59,6 +60,7 @@ const { getConfigWarnings } = require('../core/lib/config-warnings')
 // Pull-model daemons (from core/)
 const stepPoller = require('../core/lib/step-poller')
 const dagStepPoller = require('../core/lib/dag-step-poller')
+const boardTaskPoller = require('../core/lib/board-task-poller')
 const revisionWatcher = require('../core/lib/revision-watcher')
 const reflectionScheduler = require('../core/lib/reflection-scheduler')
 const threadWatcher = require('../core/lib/thread-watcher')
@@ -125,6 +127,7 @@ async function shutdown(signal) {
   // Stop pollers, runners, and scheduler
   stepPoller.stop()
   dagStepPoller.stop()
+  boardTaskPoller.stop()
   revisionWatcher.stop()
   reflectionScheduler.stop()
   threadWatcher.stop()
@@ -404,6 +407,8 @@ async function start() {
       // Start Pull-model daemons
       stepPoller.start()
       dagStepPoller.start()
+      boardTaskPoller.setRunner(boardTaskRunner)
+      boardTaskPoller.start()
       revisionWatcher.start()
       threadWatcher.start(runQuickLlmCall)
     } else {

package/mac/bin/hq

@@ -0,0 +1,4 @@
+#!/bin/bash
+# macOS HQ API helper trampoline.
+# The implementation is shared with Linux (pure bash + curl + jq).
+exec "$(dirname "$0")/../../linux/bin/hq" "$@"

package/mac/board-task-runner.js

@@ -0,0 +1,4 @@
+/**
+ * macOS board task runner — re-exports the Linux implementation.
+ */
+module.exports = require('../linux/board-task-runner')

package/mac/lib/process-manager.js

@@ -0,0 +1,109 @@
+/**
+ * Process manager detection and command building (macOS / launchd)
+ *
+ * macOS uses launchd for service management. The minion agent runs as a
+ * LaunchAgent under the dedicated `minion` user; restarts go through
+ * `launchctl kickstart -k gui/<uid>/<label>`.
+ */
+
+const { execSync } = require('child_process')
+
+// Use sudo only when not running as root (parity with linux/lib/process-manager.js).
+// Most launchctl operations on `gui/<self-uid>/...` do NOT require sudo.
+const SUDO = process.getuid && process.getuid() !== 0 ? 'sudo ' : ''
+
+// Resolve once at module load. Used to build `gui/<uid>/<label>` targets.
+function resolveUid() {
+  if (process.getuid) return process.getuid()
+  // Fallback (should never hit on macOS): query `id -u`
+  try {
+    return parseInt(execSync('id -u', { encoding: 'utf-8' }).trim(), 10)
+  } catch {
+    return 0
+  }
+}
+
+const UID = resolveUid()
+
+/**
+ * Detect the process manager.
+ * On macOS, launchd is the only option (PID 1).
+ * Returns 'standalone' only if launchctl is somehow missing — which would
+ * indicate a broken environment, since launchctl is part of the OS.
+ * @returns {'launchd' | 'standalone'}
+ */
+function detectProcessManager() {
+  try {
+    execSync('launchctl version', { stdio: 'ignore' })
+    return 'launchd'
+  } catch {
+    return 'standalone'
+  }
+}
+
+/**
+ * Build allowed commands based on detected process manager.
+ * @param {string} procMgr - Process manager type
+ * @returns {Record<string, { description: string; command: string; deferred?: boolean }>}
+ */
+function buildAllowedCommands(procMgr) {
+  const commands = {}
+
+  if (procMgr === 'launchd') {
+    const AGENT_TARGET = `gui/${UID}/com.geekbeer.minion`
+    const WEBSOCKIFY_TARGET = `gui/${UID}/com.geekbeer.websockify`
+    const TMUX_INIT_TARGET = `gui/${UID}/com.geekbeer.tmux-init`
+
+    commands['restart-agent'] = {
+      description: 'Restart the minion agent service',
+      command: `launchctl kickstart -k ${AGENT_TARGET}`,
+      deferred: true,
+    }
+    commands['update-agent'] = {
+      description: 'Update @geekbeer/minion to latest version and restart',
+      command: `${SUDO}npm install -g @geekbeer/minion@latest && launchctl kickstart -k ${AGENT_TARGET}`,
+      deferred: true,
+    }
+    commands['update-agent-dev'] = {
+      description: 'Update @geekbeer/minion from Verdaccio (dev) and restart',
+      command: `${SUDO}npm install -g @geekbeer/minion@latest --registry http://verdaccio:4873 && launchctl kickstart -k ${AGENT_TARGET}`,
+      deferred: true,
+    }
+    commands['restart-display'] = {
+      description: 'Restart websockify (noVNC bridge); native Screen Sharing is system-managed',
+      command: `launchctl kickstart -k ${WEBSOCKIFY_TARGET}`,
+    }
+    commands['restart-all'] = {
+      description: 'Restart websockify and the agent',
+      command: `launchctl kickstart -k ${WEBSOCKIFY_TARGET} && launchctl kickstart -k ${AGENT_TARGET}`,
+      deferred: true,
+    }
+    commands['status-services'] = {
+      description: 'Print status of all minion LaunchAgents',
+      command: `launchctl print ${AGENT_TARGET} 2>/dev/null | head -40 ; echo "---" ; launchctl print ${WEBSOCKIFY_TARGET} 2>/dev/null | head -20 ; echo "---" ; launchctl print ${TMUX_INIT_TARGET} 2>/dev/null | head -20`,
+    }
+  } else {
+    // Standalone mode: limited commands (launchctl unavailable — unlikely on macOS)
+    commands['update-agent'] = {
+      description: 'Update @geekbeer/minion to latest version',
+      command: `${SUDO}npm install -g @geekbeer/minion@latest`,
+    }
+    commands['update-agent-dev'] = {
+      description: 'Update @geekbeer/minion from Verdaccio (dev)',
+      command: `${SUDO}npm install -g @geekbeer/minion@latest --registry http://verdaccio:4873`,
+    }
+    commands['status-services'] = {
+      description: 'Show agent process info',
+      command: 'echo "Process Manager: standalone (launchctl unavailable)" && echo "Agent PID: $$" && echo "Node version: $(node -v)" && echo "Uptime: $(ps -o etime= -p $$)"',
+    }
+  }
+
+  return commands
+}
+
+module.exports = {
+  SUDO,
+  UID,
+  detectProcessManager,
+  buildAllowedCommands,
+}