@geekbeer/minion 3.43.0 → 3.49.1

package/core/config.js

@@ -54,11 +54,13 @@ loadEnvFile()
  * Resolve the correct home directory for the minion user.
  * On Linux, supervisord environments may set HOME=/root incorrectly.
  * This function uses MINION_USER + getent passwd to find the correct home.
+ * On macOS, LaunchAgent always inherits the correct HOME from the user's session,
+ * and `getent` is not available — so we always fall through to os.homedir().
  * On Windows, os.homedir() is always correct (returns %USERPROFILE%).
  */
 function resolveHomeDir() {
   const minionUser = process.env.MINION_USER
-  if (minionUser && process.platform !== 'win32') {
+  if (minionUser && process.platform === 'linux') {
     try {
       const entry = execSync(`getent passwd ${minionUser}`, { encoding: 'utf-8' }).trim()
       const home = entry.split(':')[5]

package/core/lib/board-task-context.js

@@ -0,0 +1,87 @@
+/**
+ * Build the system-prompt injection block for a `board_task` chat session.
+ *
+ * Used by linux/routes/chat.js and win/routes/chat.js when the incoming
+ * /api/chat call carries `context.type === 'board_task'`. Centralized here
+ * so the two platform-specific chat handlers stay in sync — board-task
+ * sessions are autonomous, so the assistant must receive identical guidance
+ * regardless of OS.
+ */
+
+function buildBoardTaskInjection(context) {
+  if (!context || context.type !== 'board_task' || !context.task) return null
+
+  const task = context.task
+  const ac = Array.isArray(task.acceptance_criteria) ? task.acceptance_criteria : []
+  const projectId = context.project_id || task.project_id
+  const lines = [
+    '[ボードタスク自動着手モード]',
+    'このセッションはボードタスクの自律着手で起動されました。ユーザーからの追加指示を待たず、',
+    '受け入れ要件を満たすまで自走してください。',
+    '',
+    `タスク: [task:${task.id}] ${task.title}`,
+    `優先度: ${task.priority || 'normal'}` + (task.due_date ? ` / 期限: ${task.due_date}` : ''),
+    `所属プロジェクト: ${projectId}`,
+  ]
+  if (context.sprint && context.sprint.name) {
+    lines.push(`所属スプリント: ${context.sprint.name} (${context.sprint.id})`)
+  }
+  if (task.description) {
+    lines.push('', '## タスク説明', String(task.description))
+  }
+  lines.push('', '## 受け入れ要件 (Definition of Done)')
+  if (ac.length > 0) {
+    for (const item of ac) {
+      const mark = item.checked ? '[x]' : '[ ]'
+      lines.push(`- ${mark} ${item.text}`)
+    }
+    lines.push(
+      '',
+      '上記すべてにチェックが入った状態で完了とみなしてください。受け入れ要件のチェックを更新するには、',
+      `PATCH \$HQ_URL/api/minion/projects/${projectId}/tasks/${task.id} の body で acceptance_criteria を渡します:`,
+      '```json',
+      '{ "acceptance_criteria": [{"id":"<既存のID>","text":"...","checked":true}, ...] }',
+      '```',
+      '※ 既存のIDを保持したまま checked のみ更新すること。新規項目は id を省略してOK (サーバが付与)。',
+    )
+  } else {
+    lines.push(
+      '⚠️ acceptance_criteria が未設定のままアクティブ化されています (DoR違反)。ユーザーに要件を確認するか、',
+      '安全側で曖昧な解釈を避け、状況を Notes/Memory に記録してから review に出してください。',
+    )
+  }
+
+  if (context.project_context_content) {
+    lines.push(
+      '',
+      '## プロジェクトコンテキスト (project_contexts.content)',
+      String(context.project_context_content),
+    )
+  }
+
+  if (Array.isArray(context.members) && context.members.length > 0) {
+    lines.push('', '## プロジェクトメンバー')
+    for (const m of context.members) {
+      const role = m.role ? ` (${m.role})` : ''
+      const name = m.name || m.display_name || m.minion_id || m.user_id || '?'
+      lines.push(`- ${name}${role}`)
+    }
+  }
+
+  lines.push(
+    '',
+    '## 完了時の操作',
+    '受け入れ要件をすべて満たしたら、以下でタスクを `review` に遷移しユーザーに引き渡してください:',
+    '```bash',
+    `curl -X PATCH -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \\`,
+    `  -d '{"status":"review"}' \\`,
+    `  \$HQ_URL/api/minion/projects/${projectId}/tasks/${task.id}`,
+    '```',
+    '途中で人間の判断が必要になった場合は、status は `doing` のまま threads (`POST /api/threads`) でPMにエスカレーションするか、',
+    'Notes/Memory に状況を記録してから review に出すこと。勝手に done に遷移しないこと。',
+  )
+
+  return lines.join('\n')
+}
+
+module.exports = { buildBoardTaskInjection }

package/core/lib/board-task-poller.js

@@ -0,0 +1,210 @@
+/**
+ * Board Task Poller
+ *
+ * Polls HQ for board tasks the minion is assigned to in an active sprint,
+ * claims them idempotently, and dispatches the work to a platform-specific
+ * board-task-runner that starts a dedicated tmux session named `bt-{id8}`.
+ *
+ * Detection criteria (server-side filter on /api/minion/board-tasks/pending):
+ *   - assignee_minion_id == self
+ *   - status IN ('todo', 'doing')
+ *   - sprint.status == 'active'
+ *
+ * Concurrency is shared with dag-step-poller via concurrency-manager so the
+ * minion never exceeds MAX_CONCURRENT autonomous jobs across both pollers.
+ *
+ * The runner is injected via setRunner() at server startup so this module
+ * stays platform-agnostic. Linux supplies linux/board-task-runner.js
+ * (direct tmux); Windows supplies win/board-task-runner.js (HTTP proxy to
+ * wsl-session-server which runs tmux inside WSL).
+ */
+
+const { config, isHqConfigured } = require('../config')
+const concurrency = require('./concurrency-manager')
+
+// Polling interval: 30 seconds (matches dag-step-poller).
+const POLL_INTERVAL_MS = 30_000
+
+let polling = false
+let pollTimer = null
+let lastPollAt = null
+let runner = null
+
+/**
+ * Inject the platform-specific runner.
+ * Required interface:
+ *   - runBoardTask({ task, contextData }): Promise<{ sessionName, started, success, error? }>
+ *   - isBoardTaskRunning(taskId): Promise<boolean>
+ *   - generateSessionName(taskId): string
+ */
+function setRunner(impl) {
+  runner = impl
+}
+
+async function hqRequest(endpoint, options = {}) {
+  if (!isHqConfigured()) {
+    return { skipped: true, reason: 'HQ not configured' }
+  }
+  const url = `${config.HQ_URL}${endpoint}`
+  const resp = await fetch(url, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.API_TOKEN}`,
+      ...(options.headers || {}),
+    },
+  })
+  const text = await resp.text()
+  let data
+  try {
+    data = text ? JSON.parse(text) : {}
+  } catch {
+    data = { raw: text }
+  }
+  if (!resp.ok) {
+    const err = new Error(data.error || `HQ ${endpoint} failed: ${resp.status}`)
+    err.statusCode = resp.status
+    err.body = data
+    throw err
+  }
+  return data
+}
+
+async function pollOnce() {
+  if (!isHqConfigured()) return
+  if (!runner) {
+    console.warn('[BoardTaskPoller] No runner injected, skipping poll')
+    return
+  }
+  if (polling) return
+
+  polling = true
+  try {
+    const data = await hqRequest('/api/minion/board-tasks/pending')
+    const tasks = data.tasks || []
+    if (tasks.length === 0) return
+
+    console.log(
+      `[BoardTaskPoller] Found ${tasks.length} pending board task(s), ` +
+      `active: ${concurrency.size()}/${concurrency.MAX_CONCURRENT}`,
+    )
+
+    for (const task of tasks) {
+      const key = `board-task:${task.id}`
+      if (concurrency.has(key)) continue
+
+      // Local-session check: if a tmux session for this task is already
+      // alive on this minion, the work is in progress — skip claiming and
+      // let the running session finish. This handles minion restarts and
+      // sprint carry-overs naturally.
+      try {
+        if (await runner.isBoardTaskRunning(task.id)) {
+          console.log(`[BoardTaskPoller] Task ${task.id} already running locally, skipping`)
+          continue
+        }
+      } catch (err) {
+        console.error(`[BoardTaskPoller] Local session check failed for ${task.id}: ${err.message}`)
+      }
+
+      if (!concurrency.acquire(key, 'board-task')) break
+
+      claimAndStart(task)
+        .catch(err => {
+          console.error(`[BoardTaskPoller] task ${task.id} error: ${err.message}`)
+        })
+        .finally(() => {
+          concurrency.release(key)
+        })
+    }
+  } catch (err) {
+    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+      console.log('[BoardTaskPoller] HQ unreachable, will retry next cycle')
+    } else {
+      console.error(`[BoardTaskPoller] Poll error: ${err.message}`)
+    }
+  } finally {
+    polling = false
+    lastPollAt = new Date().toISOString()
+  }
+}
+
+async function claimAndStart(task) {
+  // 1. Idempotent claim. 409 = sprint inactive / status moved off doing — skip.
+  let claimed
+  try {
+    claimed = await hqRequest(`/api/minion/board-tasks/${task.id}/claim`, { method: 'POST' })
+  } catch (err) {
+    if (err.statusCode === 409 || err.statusCode === 403) {
+      console.log(`[BoardTaskPoller] Task ${task.id} no longer claimable: ${err.message}`)
+      return
+    }
+    throw err
+  }
+  const claimedTask = claimed.task || task
+  if (claimed.was_already_doing) {
+    console.log(`[BoardTaskPoller] Task ${task.id} was already 'doing' (carry-over), starting runner`)
+  }
+
+  // 2. Best-effort fetch of project context + members to enrich the prompt.
+  const [projectContext, members] = await Promise.all([
+    hqRequest(`/api/minion/me/project/${claimedTask.project_id}/context`).catch(() => null),
+    hqRequest(`/api/minion/me/project/${claimedTask.project_id}/members`).catch(() => null),
+  ])
+
+  // 3. Hand off to the platform-specific runner.
+  const result = await runner.runBoardTask({
+    task: claimedTask,
+    contextData: {
+      sprint: task.sprint || null,
+      projectContextContent: projectContext?.content || null,
+      members: Array.isArray(members?.members) ? members.members : null,
+    },
+  })
+
+  if (result.success) {
+    console.log(
+      `[BoardTaskPoller] Task ${claimedTask.id} runner finished ` +
+      `(session=${result.sessionName}, started=${result.started})`,
+    )
+  } else {
+    console.error(
+      `[BoardTaskPoller] Task ${claimedTask.id} runner failed: ${result.error || 'unknown'}`,
+    )
+  }
+}
+
+function start() {
+  if (!isHqConfigured()) {
+    console.log('[BoardTaskPoller] HQ not configured, board task poller disabled')
+    return
+  }
+  if (!runner) {
+    console.warn('[BoardTaskPoller] start() called before setRunner(), poller will be inert')
+  }
+  // Stagger start slightly after dag-step-poller (which starts at +7s).
+  setTimeout(() => pollOnce(), 11_000)
+  pollTimer = setInterval(() => pollOnce(), POLL_INTERVAL_MS)
+  console.log(
+    `[BoardTaskPoller] Started (polling every ${POLL_INTERVAL_MS / 1000}s, ` +
+    `max concurrent: ${concurrency.MAX_CONCURRENT} shared)`,
+  )
+}
+
+function stop() {
+  if (pollTimer) {
+    clearInterval(pollTimer)
+    pollTimer = null
+    console.log('[BoardTaskPoller] Stopped')
+  }
+}
+
+function getStatus() {
+  return {
+    running: pollTimer !== null,
+    last_poll_at: lastPollAt,
+    concurrency: concurrency.snapshot(),
+    runner_attached: !!runner,
+  }
+}
+
+module.exports = { start, stop, pollOnce, getStatus, setRunner }

package/core/lib/concurrency-manager.js

@@ -0,0 +1,56 @@
+/**
+ * Concurrency Manager
+ *
+ * Shared semaphore for poller-driven autonomous work (DAG nodes + board tasks).
+ * Each poller registers an active job with a unique key so the global
+ * concurrency cap is enforced even when multiple pollers run side-by-side.
+ *
+ * The cap matches the pre-existing dag-step-poller value (2) — keeping a
+ * single global limit avoids accidental over-subscription when the minion
+ * has both DAG and board work simultaneously.
+ */
+
+const MAX_CONCURRENT = 2
+
+const active = new Map() // key -> { kind, startedAt }
+
+function size() {
+  return active.size
+}
+
+function has(key) {
+  return active.has(key)
+}
+
+function isFull() {
+  return active.size >= MAX_CONCURRENT
+}
+
+function acquire(key, kind) {
+  if (active.has(key)) return false
+  if (active.size >= MAX_CONCURRENT) return false
+  active.set(key, { kind, startedAt: new Date().toISOString() })
+  return true
+}
+
+function release(key) {
+  active.delete(key)
+}
+
+function snapshot() {
+  return {
+    active: active.size,
+    max_concurrent: MAX_CONCURRENT,
+    jobs: Array.from(active.entries()).map(([key, meta]) => ({ key, ...meta })),
+  }
+}
+
+module.exports = {
+  MAX_CONCURRENT,
+  size,
+  has,
+  isFull,
+  acquire,
+  release,
+  snapshot,
+}

package/core/lib/dag-step-poller.js

@@ -12,19 +12,22 @@
 const { config, isHqConfigured } = require('../config')
 const api = require('../api')
 const variableStore = require('../stores/variable-store')
+const concurrency = require('./concurrency-manager')
 
 // Polling interval: 30 seconds (matches step-poller)
 const POLL_INTERVAL_MS = 30_000
 
-// Maximum concurrent DAG nodes this minion can execute
-const MAX_CONCURRENT = 2
+// Concurrency is enforced by the shared concurrency-manager (MAX_CONCURRENT=2).
+// This poller shares the cap with board-task-poller so the minion never runs
+// more than MAX_CONCURRENT autonomous jobs at once.
 
 // Prevent concurrent poll cycles
 let polling = false
 let pollTimer = null
 let lastPollAt = null
 
-// Track active node executions: nodeExecId -> Promise
+// Track active node executions: nodeExecId -> Promise (kept for legacy callers
+// of getStatus(); the authoritative cap is in concurrency-manager).
 const activeNodes = new Map()
 
 /**
@@ -67,21 +70,24 @@ async function pollOnce() {
 
     if (!data.nodes || data.nodes.length === 0) return
 
-    console.log(`[DagPoller] Found ${data.nodes.length} pending node(s), active: ${activeNodes.size}/${MAX_CONCURRENT}`)
+    console.log(`[DagPoller] Found ${data.nodes.length} pending node(s), active: ${concurrency.size()}/${concurrency.MAX_CONCURRENT}`)
 
     for (const node of data.nodes) {
-      if (activeNodes.size >= MAX_CONCURRENT) break
-      if (activeNodes.has(node.node_execution_id)) continue
+      const key = `dag:${node.node_execution_id}`
+      if (concurrency.has(key)) continue
+      if (!concurrency.acquire(key, 'dag')) break
 
+      activeNodes.set(node.node_execution_id, true)
       const promise = executeNode(node)
         .catch(err => {
           console.error(`[DagPoller] Node ${node.node_id} execution error: ${err.message}`)
         })
         .finally(() => {
+          concurrency.release(key)
           activeNodes.delete(node.node_execution_id)
         })
-
-      activeNodes.set(node.node_execution_id, promise)
+      // eslint-disable-next-line no-unused-expressions
+      promise
     }
   } catch (err) {
     if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
@@ -483,7 +489,7 @@ function start() {
 
   setTimeout(() => pollOnce(), 7000) // Slightly delayed after step-poller
   pollTimer = setInterval(() => pollOnce(), POLL_INTERVAL_MS)
-  console.log(`[DagPoller] Started (polling every ${POLL_INTERVAL_MS / 1000}s, max concurrent: ${MAX_CONCURRENT})`)
+  console.log(`[DagPoller] Started (polling every ${POLL_INTERVAL_MS / 1000}s, max concurrent: ${concurrency.MAX_CONCURRENT} shared)`)
 }
 
 function stop() {
@@ -499,7 +505,7 @@ function getStatus() {
     running: pollTimer !== null,
     last_poll_at: lastPollAt,
     active_nodes: activeNodes.size,
-    max_concurrent: MAX_CONCURRENT,
+    max_concurrent: concurrency.MAX_CONCURRENT,
   }
 }
 

package/core/lib/end-of-day.js

@@ -29,11 +29,25 @@ async function runEndOfDay({ workspaceId, runQuickLlmCall, clearSession = false
     throw new Error('workspaceId is required for end-of-day processing')
   }
 
-  const today = new Date().toISOString().split('T')[0]
-  const session = await chatStore.load(workspaceId)
+  // Use the system's local timezone so that `today` and the message-window
+  // boundaries match the cron schedule (which fires in local TZ).
+  const now = new Date()
+  const yyyy = now.getFullYear()
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const dd = String(now.getDate()).padStart(2, '0')
+  const today = `${yyyy}-${mm}-${dd}`
+  const dayStart = new Date(yyyy, now.getMonth(), now.getDate()).getTime()
+  const dayEnd = dayStart + 24 * 60 * 60 * 1000
 
-  // No conversation — record a stub so the idle day is still logged.
-  if (!session || session.messages.length === 0) {
+  const session = await chatStore.load(workspaceId)
+  const todayMessages = (session?.messages || []).filter(
+    m => typeof m.timestamp === 'number' && m.timestamp >= dayStart && m.timestamp < dayEnd
+  )
+
+  // No conversation today — record a stub so the idle day is still logged.
+  // (Past messages may remain in the session; they are intentionally excluded
+  // from today's summary.)
+  if (todayMessages.length === 0) {
     const ws = workspaceId ? workspaceStore.getById(workspaceId) : null
     const wsLabel = ws ? `${ws.name}` : (workspaceId ? `workspace:${workspaceId}` : '未所属')
     const stub = `# ${today} (${wsLabel})\n\n本日、このワークスペースでの会話はありませんでした。`
@@ -42,8 +56,8 @@ async function runEndOfDay({ workspaceId, runQuickLlmCall, clearSession = false
     return { daily_log: today, memory_entries_added: 0, had_conversation: false }
   }
 
-  // Build conversation text for summarization (last 50 messages)
-  const messages = session.messages.slice(-50)
+  // Build conversation text for summarization (last 50 messages of today)
+  const messages = todayMessages.slice(-50)
   const conversationText = messages
     .map(m => `${m.role === 'user' ? 'ユーザー' : 'アシスタント'}: ${m.content.substring(0, 500)}`)
     .join('\n\n')

package/core/lib/platform.js

@@ -11,19 +11,21 @@ const path = require('path')
 const fs = require('fs')
 
 const IS_WINDOWS = process.platform === 'win32'
+const IS_MAC = process.platform === 'darwin'
 const PATH_SEPARATOR = path.delimiter // ';' on Windows, ':' on Unix
 const TEMP_DIR = os.tmpdir()
 
 /**
  * Resolve the data directory for minion agent persistent files.
  * Windows: %USERPROFILE%\.minion (matches minion-cli.ps1 / start-agent.ps1)
+ * macOS:   ~/.minion (LaunchAgent runs as user, cannot write to /opt)
  * Linux:   /opt/minion-agent (existing behavior)
  */
 function resolveDataDir() {
-  if (IS_WINDOWS) {
-    // Use ~/.minion to match minion-cli.ps1 and start-agent.ps1.
-    // All Windows-specific code (CLI, process-manager, server.js) uses ~/.minion
-    // as the canonical data directory, so core modules must align with it.
+  if (IS_WINDOWS || IS_MAC) {
+    // Windows: matches minion-cli.ps1 / start-agent.ps1
+    // macOS: LaunchAgent context — agent runs as the dedicated `minion` user,
+    // so persistent state lives under that user's home.
     return path.join(os.homedir(), '.minion')
   }
   return '/opt/minion-agent'
@@ -39,21 +41,38 @@ const LOG_DIR = path.join(DATA_DIR, 'logs')
  * @returns {string} Extended PATH string
  */
 function buildExtendedPath(homeDir) {
-  const additionalPaths = IS_WINDOWS
-    ? [
-        path.join(homeDir, '.local', 'bin'),
-        path.join(homeDir, '.npm-global'),
-        path.join(homeDir, '.claude', 'bin'),
-        path.join(homeDir, 'AppData', 'Roaming', 'npm'),
-        path.join(process.env.PROGRAMFILES || 'C:\\Program Files', 'nodejs'),
-      ]
-    : [
-        path.join(homeDir, 'bin'),
-        path.join(homeDir, '.npm-global', 'bin'),
-        path.join(homeDir, '.local', 'bin'),
-        path.join(homeDir, '.claude', 'bin'),
-        '/usr/local/bin',
-      ]
+  let additionalPaths
+  if (IS_WINDOWS) {
+    additionalPaths = [
+      path.join(homeDir, '.local', 'bin'),
+      path.join(homeDir, '.npm-global'),
+      path.join(homeDir, '.claude', 'bin'),
+      path.join(homeDir, 'AppData', 'Roaming', 'npm'),
+      path.join(process.env.PROGRAMFILES || 'C:\\Program Files', 'nodejs'),
+    ]
+  } else if (IS_MAC) {
+    additionalPaths = [
+      // Homebrew (Apple Silicon)
+      '/opt/homebrew/bin',
+      '/opt/homebrew/sbin',
+      // Homebrew (Intel)
+      '/usr/local/bin',
+      '/usr/local/sbin',
+      // User-local
+      path.join(homeDir, 'bin'),
+      path.join(homeDir, '.npm-global', 'bin'),
+      path.join(homeDir, '.local', 'bin'),
+      path.join(homeDir, '.claude', 'bin'),
+    ]
+  } else {
+    additionalPaths = [
+      path.join(homeDir, 'bin'),
+      path.join(homeDir, '.npm-global', 'bin'),
+      path.join(homeDir, '.local', 'bin'),
+      path.join(homeDir, '.claude', 'bin'),
+      '/usr/local/bin',
+    ]
+  }
 
   const currentPath = process.env.PATH || ''
   return [...additionalPaths, currentPath].join(PATH_SEPARATOR)
@@ -99,6 +118,7 @@ function resolveEnvFilePath(homeDir) {
 
 module.exports = {
   IS_WINDOWS,
+  IS_MAC,
   PATH_SEPARATOR,
   TEMP_DIR,
   DATA_DIR,

package/core/routes/daemons.js

@@ -9,6 +9,7 @@
 
 const stepPoller = require('../lib/step-poller')
 const dagStepPoller = require('../lib/dag-step-poller')
+const boardTaskPoller = require('../lib/board-task-poller')
 const revisionWatcher = require('../lib/revision-watcher')
 const threadWatcher = require('../lib/thread-watcher')
 const reflectionScheduler = require('../lib/reflection-scheduler')
@@ -24,6 +25,7 @@ async function daemonRoutes(fastify, opts) {
       daemons: {
         step_poller: stepPoller.getStatus(),
         dag_step_poller: dagStepPoller.getStatus(),
+        board_task_poller: boardTaskPoller.getStatus(),
         revision_watcher: revisionWatcher.getStatus(),
         thread_watcher: threadWatcher.getStatus(),
         reflection_scheduler: reflectionScheduler.getStatus(),

package/core/routes/diagnose.js

@@ -18,7 +18,7 @@ const { execSync } = require('child_process')
 const { config, isHqConfigured } = require('../config')
 const { version } = require('../../package.json')
 const { getLlmServices, isLlmCommandConfigured } = require('../lib/llm-checker')
-const { IS_WINDOWS } = require('../lib/platform')
+const { IS_WINDOWS, IS_MAC } = require('../lib/platform')
 const { getStatus } = require('./health')
 
 /**
@@ -62,6 +62,14 @@ function isPortListening(port) {
         stdio: 'pipe',
       })
       return out.includes('LISTENING')
+    } else if (IS_MAC) {
+      // macOS: ss does not exist; use lsof (canonical on macOS)
+      const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN 2>/dev/null`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: 'pipe',
+      })
+      return out.trim().length > 0
     } else {
       const out = execSync(`ss -tlnp 2>/dev/null | grep ":${port} " || netstat -tlnp 2>/dev/null | grep ":${port} "`, {
         encoding: 'utf-8',
@@ -159,6 +167,23 @@ function checkVnc() {
     }
   }
 
+  if (IS_MAC) {
+    // macOS: native Screen Sharing (screensharingd) + Node-based vnc-auth-proxy
+    // (replaces websockify as of v3.47.8). The proxy listens on 6080 and
+    // performs RFB auth against screensharingd:5900 using a local password.
+    const screensharingd = isProcessRunning('screensharingd') || isProcessRunning('ARDAgent')
+    const vncBackend = isPortListening(5900)
+    const vncProxy = isPortListening(6080)
+    return {
+      running: vncBackend && vncProxy,
+      details: [
+        `screensharingd: ${screensharingd ? 'running' : 'NOT RUNNING (enable: System Settings -> Sharing -> Screen Sharing)'}`,
+        `Screen Sharing (:5900): ${vncBackend ? 'listening' : 'NOT LISTENING'}`,
+        `vnc-auth-proxy (:6080): ${vncProxy ? 'listening' : 'NOT LISTENING'}`,
+      ].join(', '),
+    }
+  }
+
   // Linux: Xvfb + VNC server (x0vncserver or x11vnc) + websockify (noVNC)
   const xvfb = isProcessRunning('Xvfb')
   const x0vnc = isProcessRunning('x0vncserver') || isProcessRunning('X0tigervnc')
@@ -288,7 +313,7 @@ async function diagnoseRoutes(fastify) {
     return {
       summary: allOk ? 'ALL OK' : `${okCount}/${totalCount} checks passed`,
       version,
-      platform: IS_WINDOWS ? 'windows' : 'linux',
+      platform: IS_WINDOWS ? 'windows' : IS_MAC ? 'darwin' : 'linux',
       timestamp: new Date().toISOString(),
       current_task: currentTask,
       checks,