@geekbeer/minion 2.6.0 → 2.10.2

package/README.md

@@ -37,6 +37,19 @@ minion-cli health     # Run health check
 minion-cli log -m "Task completed" -l info -s skill-name
 ```
 
+### Issue Reporting
+
+```javascript
+const { reportIssue } = require('@geekbeer/minion/api')
+
+await reportIssue({
+  title: 'HQ APIで502エラーが発生する',
+  body: '## 状況\n...\n\n## 再現手順\n...',
+  labels: ['bug', 'critical']
+})
+// → { success: true, issue_url: '...', issue_number: 42 }
+```
+
 ## Environment Variables
 
 | Variable | Description | Default |

package/api.js

@@ -50,7 +50,33 @@ async function reportExecution(data) {
   })
 }
 
+/**
+ * Report a single workflow step completion to HQ.
+ * Called by the post-execution hook after a dispatched skill finishes.
+ * @param {object} data - { workflow_execution_id, step_index, status }
+ */
+async function reportStepComplete(data) {
+  return request('/step-complete', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  })
+}
+
+/**
+ * Create a GitHub Issue via HQ for bug reports or enhancement suggestions
+ * @param {object} data - { title: string, body: string, labels?: string[] }
+ * @returns {Promise<{ success: boolean, issue_url: string, issue_number: number }>}
+ */
+async function reportIssue(data) {
+  return request('/report', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  })
+}
+
 module.exports = {
   request,
   reportExecution,
+  reportStepComplete,
+  reportIssue,
 }

package/config.js

@@ -11,8 +11,32 @@
  *
  * Other optional environment variables:
  * - AGENT_PORT: Port for the local agent server (default: 3001)
+ * - MINION_USER: System user running the agent (used to resolve home directory)
  */
 
+const os = require('os')
+const { execSync } = require('child_process')
+
+/**
+ * Resolve the correct home directory for the minion user.
+ * In supervisord environments, os.homedir() may return /root because
+ * the HOME env var is not inherited. This function uses MINION_USER
+ * (set in .env during setup) to look up the correct home via getent passwd.
+ */
+function resolveHomeDir() {
+  const minionUser = process.env.MINION_USER
+  if (minionUser) {
+    try {
+      const entry = execSync(`getent passwd ${minionUser}`, { encoding: 'utf-8' }).trim()
+      const home = entry.split(':')[5]
+      if (home) return home
+    } catch {
+      // getent failed — fall back to os.homedir()
+    }
+  }
+  return os.homedir()
+}
+
 const config = {
   // HQ Server Configuration (optional - omit for standalone mode)
   HQ_URL: process.env.HQ_URL || '',
@@ -21,6 +45,9 @@ const config = {
 
   // Server settings
   AGENT_PORT: parseInt(process.env.AGENT_PORT, 10) || 3001,
+
+  // Resolved home directory (safe for supervisord environments)
+  HOME_DIR: resolveHomeDir(),
 }
 
 /**

package/execution-store.js

@@ -6,7 +6,8 @@
 
 const fs = require('fs').promises
 const path = require('path')
-const os = require('os')
+
+const { config } = require('./config')
 
 // Max executions to keep (older ones are pruned)
 const MAX_EXECUTIONS = 200
@@ -21,7 +22,7 @@ function getExecutionFilePath() {
     require('fs').accessSync(path.dirname(optPath))
     return optPath
   } catch {
-    return path.join(os.homedir(), 'executions.json')
+    return path.join(config.HOME_DIR, 'executions.json')
   }
 }
 

package/lib/llm-checker.js

@@ -0,0 +1,114 @@
+/**
+ * LLM Service authentication checker
+ *
+ * Detects whether supported LLM CLIs are authenticated and ready to use.
+ * CLIs are pre-installed on all minions; this module only checks auth status.
+ * Results are cached in memory for 60 seconds to avoid excessive filesystem checks.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { config } = require('../config')
+
+const CACHE_TTL_MS = 60000
+
+let cachedResult = null
+let cachedAt = 0
+
+/**
+ * Check Claude Code authentication.
+ * Claude stores OAuth credentials in ~/.claude/.credentials.json
+ */
+function isClaudeAuthenticated() {
+  const candidates = [
+    path.join(config.HOME_DIR, '.claude', '.credentials.json'),
+    path.join(config.HOME_DIR, '.claude', 'credentials.json'),
+  ]
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const content = fs.readFileSync(p, 'utf-8')
+        const parsed = JSON.parse(content)
+        if (parsed && Object.keys(parsed).length > 0) return true
+      }
+    } catch {
+      // Invalid JSON or read error — not authenticated
+    }
+  }
+  return false
+}
+
+/**
+ * Check Gemini CLI authentication.
+ * Gemini uses Google OAuth tokens or API key env vars.
+ */
+function isGeminiAuthenticated() {
+  if (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY) return true
+
+  const possiblePaths = [
+    path.join(config.HOME_DIR, '.config', 'gemini'),
+    path.join(config.HOME_DIR, '.config', 'gcloud', 'application_default_credentials.json'),
+  ]
+  for (const p of possiblePaths) {
+    try {
+      if (!fs.existsSync(p)) continue
+      const stat = fs.statSync(p)
+      if (stat.isDirectory()) {
+        if (fs.readdirSync(p).length > 0) return true
+      } else {
+        if (fs.readFileSync(p, 'utf-8').trim().length > 0) return true
+      }
+    } catch {
+      // Ignore
+    }
+  }
+  return false
+}
+
+/**
+ * Check Codex (OpenAI) authentication.
+ * Codex CLI uses OPENAI_API_KEY or config in ~/.codex/
+ */
+function isCodexAuthenticated() {
+  if (process.env.OPENAI_API_KEY) return true
+
+  const codexConfig = path.join(config.HOME_DIR, '.codex')
+  try {
+    if (fs.existsSync(codexConfig) && fs.statSync(codexConfig).isDirectory()) {
+      if (fs.readdirSync(codexConfig).length > 0) return true
+    }
+  } catch {
+    // Ignore
+  }
+  return false
+}
+
+const SERVICE_DEFINITIONS = [
+  { name: 'claude', display_name: 'Claude Code', check: isClaudeAuthenticated },
+  { name: 'gemini', display_name: 'Gemini CLI', check: isGeminiAuthenticated },
+  { name: 'codex', display_name: 'Codex', check: isCodexAuthenticated },
+]
+
+/**
+ * Get authenticated LLM services (cached for 60s).
+ * Returns all services with their authentication status.
+ * @returns {{ name: string, display_name: string, authenticated: boolean }[]}
+ */
+function getLlmServices() {
+  const now = Date.now()
+  if (cachedResult && (now - cachedAt) < CACHE_TTL_MS) {
+    return cachedResult
+  }
+
+  const services = SERVICE_DEFINITIONS.map(({ name, display_name, check }) => ({
+    name,
+    display_name,
+    authenticated: check(),
+  }))
+
+  cachedResult = services
+  cachedAt = now
+  return services
+}
+
+module.exports = { getLlmServices }

package/minion-cli.sh

@@ -88,6 +88,17 @@ svc_control() {
 
 AGENT_URL="${MINION_AGENT_URL:-http://localhost:3001}"
 
+# Auto-load .env so that API_TOKEN etc. are available in interactive shells
+ENV_FILE="/opt/minion-agent/.env"
+if [ -f "$ENV_FILE" ] && [ -r "$ENV_FILE" ]; then
+  while IFS='=' read -r key value; do
+    [[ "$key" =~ ^#.*$ || -z "$key" ]] && continue
+    if [ -z "${!key:-}" ]; then
+      export "$key=$value"
+    fi
+  done < "$ENV_FILE"
+fi
+
 # ============================================================
 # setup subcommand
 # ============================================================
@@ -405,10 +416,10 @@ After=xvfb.service
 Requires=xvfb.service
 
 [Service]
-Type=forking
+Type=simple
 User=${TARGET_USER}
 Environment=DISPLAY=:99
-ExecStart=/usr/bin/autocutsel -fork
+ExecStart=/usr/bin/autocutsel
 Restart=always
 RestartSec=5
 
@@ -487,8 +498,9 @@ NVNCEOF
 
     supervisord)
       # Build environment line from .env values
+      # Include HOME and DISPLAY since supervisord does not set them when switching user
       local ENV_LINE="environment="
-      local ENV_PAIRS=()
+      local ENV_PAIRS=("HOME=\"${TARGET_HOME}\"" "DISPLAY=\":99\"")
       while IFS='=' read -r key value; do
         [[ -z "$key" || "$key" == \#* ]] && continue
         ENV_PAIRS+=("${key}=\"${value}\"")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "2.6.0",
+  "version": "2.10.2",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "server.js",
   "bin": {

package/routes/directives.js

@@ -0,0 +1,163 @@
+/**
+ * Directive endpoints
+ *
+ * Receives temp skill directives from HQ and executes them.
+ * Used for one-shot workflow orchestration via system-embedded skills.
+ *
+ * Endpoints:
+ * - POST /api/directive - Receive and execute a temp skill directive
+ */
+
+const fs = require('fs').promises
+const path = require('path')
+const crypto = require('crypto')
+
+const { verifyToken } = require('../lib/auth')
+const { config } = require('../config')
+const { writeSkillToLocal } = require('./skills')
+const workflowRunner = require('../workflow-runner')
+const executionStore = require('../execution-store')
+const logManager = require('../lib/log-manager')
+
+/**
+ * Parse frontmatter from skill content to extract body
+ * @param {string} content - Full skill content with frontmatter
+ * @returns {{ metadata: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
+  if (!match) return { metadata: {}, body: content }
+
+  const metadata = {}
+  for (const line of match[1].split('\n')) {
+    const [key, ...rest] = line.split(':')
+    if (key && rest.length) {
+      metadata[key.trim()] = rest.join(':').trim()
+    }
+  }
+  return { metadata, body: match[2].trimStart() }
+}
+
+/**
+ * Register directive routes as Fastify plugin
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+async function directiveRoutes(fastify) {
+  // Receive and execute a temp skill directive from HQ
+  fastify.post('/api/directive', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const { skill_name, skill_content, execution_id, context } = request.body || {}
+
+    if (!skill_name || !skill_content) {
+      reply.code(400)
+      return { success: false, error: 'skill_name and skill_content are required' }
+    }
+
+    // Validate temp skill name (must start with __)
+    if (!skill_name.startsWith('__')) {
+      reply.code(400)
+      return { success: false, error: 'Directive skill names must start with __' }
+    }
+
+    const effectiveExecutionId = execution_id || crypto.randomUUID()
+    const sessionName = `dir-${effectiveExecutionId.substring(0, 8)}-${effectiveExecutionId.substring(8, 12)}`
+
+    console.log(`[Directive] Received directive: ${skill_name} (execution: ${effectiveExecutionId})`)
+    console.log(`[Directive] Session: ${sessionName}`)
+
+    try {
+      // 1. Write temp skill to local filesystem
+      // The skill_content is the full content with frontmatter — write as-is
+      const homeDir = config.HOME_DIR
+      const skillDir = path.join(homeDir, '.claude', 'skills', skill_name)
+      await fs.mkdir(skillDir, { recursive: true })
+      await fs.writeFile(path.join(skillDir, 'SKILL.md'), skill_content, 'utf-8')
+
+      console.log(`[Directive] Temp skill written: ${skillDir}`)
+    } catch (err) {
+      console.error(`[Directive] Failed to write temp skill: ${err.message}`)
+      reply.code(500)
+      return { success: false, error: `Failed to write temp skill: ${err.message}` }
+    }
+
+    const startedAt = new Date().toISOString()
+    const logFile = logManager.getLogPath(effectiveExecutionId)
+    const workflowName = context?.workflow_name || skill_name
+
+    // Save initial execution record
+    await executionStore.save({
+      id: effectiveExecutionId,
+      skill_name,
+      workflow_id: null,
+      workflow_name: workflowName,
+      status: 'running',
+      outcome: null,
+      started_at: startedAt,
+      completed_at: null,
+      parent_execution_id: null,
+      error_message: null,
+      log_file: logFile,
+    })
+
+    // 2. Run async — respond immediately with 202
+    const executionPromise = (async () => {
+      const homeDir = config.HOME_DIR
+      const skillDir = path.join(homeDir, '.claude', 'skills', skill_name)
+
+      try {
+        // Execute as a single-skill workflow
+        // skipExecutionReport: the orchestration template has its own
+        // completion report (section 5), so /execution-report is redundant
+        // and would use the wrong (local) execution ID.
+        const result = await workflowRunner.runWorkflow({
+          id: effectiveExecutionId,
+          name: workflowName,
+          pipeline_skill_names: [skill_name],
+        }, { skipExecutionReport: true })
+
+        console.log(`[Directive] Execution completed: ${skill_name} (success: ${result.execution_id ? 'yes' : 'no'})`)
+      } catch (err) {
+        console.error(`[Directive] Execution failed: ${err.message}`)
+        await executionStore.save({
+          id: effectiveExecutionId,
+          skill_name,
+          workflow_id: null,
+          workflow_name: workflowName,
+          status: 'failed',
+          outcome: 'failure',
+          started_at: startedAt,
+          completed_at: new Date().toISOString(),
+          parent_execution_id: null,
+          error_message: err.message,
+          log_file: logFile,
+        })
+      } finally {
+        // 3. Cleanup temp skill directory
+        try {
+          await fs.rm(skillDir, { recursive: true, force: true })
+          console.log(`[Directive] Temp skill cleaned up: ${skillDir}`)
+        } catch (cleanupErr) {
+          console.error(`[Directive] Failed to cleanup temp skill: ${cleanupErr.message}`)
+        }
+      }
+    })()
+
+    executionPromise.catch(err => {
+      console.error(`[Directive] Unhandled error: ${err.message}`)
+    })
+
+    reply.code(202)
+    return {
+      success: true,
+      session_name: sessionName,
+      execution_id: effectiveExecutionId,
+      message: 'Directive accepted',
+    }
+  })
+}
+
+module.exports = { directiveRoutes }

package/routes/files.js

@@ -14,13 +14,13 @@
 const fs = require('fs').promises
 const fsSync = require('fs')
 const path = require('path')
-const os = require('os')
 const { spawn } = require('child_process')
 
 const { verifyToken } = require('../lib/auth')
+const { config } = require('../config')
 
 /** Base directory for file storage */
-const FILES_DIR = path.join(os.homedir(), 'files')
+const FILES_DIR = path.join(config.HOME_DIR, 'files')
 
 /** Max upload size: 50MB */
 const MAX_UPLOAD_SIZE = 50 * 1024 * 1024

package/routes/health.js

@@ -8,6 +8,7 @@
  */
 
 const { version } = require('../package.json')
+const { getLlmServices } = require('../lib/llm-checker')
 
 // Shared status state
 let currentStatus = 'online'
@@ -48,6 +49,7 @@ async function healthRoutes(fastify) {
       uptime: process.uptime(),
       version,
       timestamp: new Date().toISOString(),
+      llm_services: getLlmServices(),
     }
   })
 

package/routes/index.js

@@ -48,6 +48,9 @@
  *   GET    /api/files/*             - Download a file (auth required)
  *   POST   /api/files/*             - Upload a file (auth required)
  *   DELETE /api/files/*             - Delete a file (auth required)
+ *
+ * Directives (routes/directives.js)
+ *   POST /api/directive             - Receive and execute a temp skill directive (auth required)
  * ─────────────────────────────────────────────────────────────────────────────
  */
 
@@ -58,6 +61,7 @@ const { workflowRoutes } = require('./workflows')
 const { routineRoutes } = require('./routines')
 const { terminalRoutes } = require('./terminal')
 const { fileRoutes } = require('./files')
+const { directiveRoutes } = require('./directives')
 
 /**
  * Register all routes with Fastify instance
@@ -71,6 +75,7 @@ async function registerRoutes(fastify) {
   await fastify.register(routineRoutes)
   await fastify.register(terminalRoutes)
   await fastify.register(fileRoutes)
+  await fastify.register(directiveRoutes)
 }
 
 module.exports = {

package/routes/skills.js

@@ -7,15 +7,19 @@
  * - POST /api/skills/push/:name  - Push local skill to HQ
  * - POST /api/skills/fetch/:name - Fetch skill from HQ and deploy locally
  * - GET  /api/skills/remote      - List skills on HQ
+ * - POST /api/skills/run         - Run a single deployed skill in a tmux session
  */
 
 const fs = require('fs').promises
 const path = require('path')
-const os = require('os')
+const crypto = require('crypto')
 
 const { verifyToken } = require('../lib/auth')
 const api = require('../api')
-const { isHqConfigured } = require('../config')
+const { config, isHqConfigured } = require('../config')
+const workflowRunner = require('../workflow-runner')
+const executionStore = require('../execution-store')
+const logManager = require('../lib/log-manager')
 
 /**
  * Parse YAML frontmatter from SKILL.md content
@@ -49,7 +53,7 @@ function parseFrontmatter(content) {
  * @returns {Promise<{path: string, references_count: number}>}
  */
 async function writeSkillToLocal(name, { content, description, display_name, references = [] }) {
-  const skillDir = path.join(os.homedir(), '.claude', 'skills', name)
+  const skillDir = path.join(config.HOME_DIR, '.claude', 'skills', name)
   const referencesDir = path.join(skillDir, 'references')
 
   await fs.mkdir(skillDir, { recursive: true })
@@ -88,7 +92,7 @@ async function writeSkillToLocal(name, { content, description, display_name, ref
  * @throws {Error} If skill not found locally or HQ rejects
  */
 async function pushSkillToHQ(name) {
-  const homeDir = os.homedir()
+  const homeDir = config.HOME_DIR
   const skillDir = path.join(homeDir, '.claude', 'skills', name)
   const skillMdPath = path.join(skillDir, 'SKILL.md')
 
@@ -135,7 +139,7 @@ async function skillRoutes(fastify) {
     console.log('[Skills] Listing deployed skills')
 
     try {
-      const homeDir = os.homedir()
+      const homeDir = config.HOME_DIR
       const skillsDir = path.join(homeDir, '.claude', 'skills')
 
       // Check if skills directory exists
@@ -276,6 +280,121 @@ async function skillRoutes(fastify) {
     }
   })
 
+  // Run a single deployed skill in a tmux session
+  // Called by HQ dispatch-step to execute a skill on this minion
+  fastify.post('/api/skills/run', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const { skill_name, execution_id, step_index, workflow_name } = request.body || {}
+
+    if (!skill_name) {
+      reply.code(400)
+      return { success: false, error: 'skill_name is required' }
+    }
+
+    // Verify skill exists locally
+    const homeDir = config.HOME_DIR
+    const skillMdPath = path.join(homeDir, '.claude', 'skills', skill_name, 'SKILL.md')
+    try {
+      await fs.access(skillMdPath)
+    } catch {
+      reply.code(404)
+      return { success: false, error: `Skill not found locally: ${skill_name}` }
+    }
+
+    const effectiveExecutionId = execution_id || crypto.randomUUID()
+    const stepLabel = step_index != null ? `-${step_index}` : ''
+    const sessionName = `step-${effectiveExecutionId.substring(0, 8)}${stepLabel}`
+
+    console.log(`[Skills] Running skill: ${skill_name} (session: ${sessionName})`)
+
+    // Build a synthetic workflow object for executeWorkflowSession-like execution
+    const skillNames = [skill_name]
+    const startedAt = new Date().toISOString()
+    const logFile = logManager.getLogPath(effectiveExecutionId)
+
+    // Save initial execution record
+    await executionStore.save({
+      id: effectiveExecutionId,
+      skill_name,
+      workflow_id: null,
+      workflow_name: workflow_name || null,
+      status: 'running',
+      outcome: null,
+      started_at: startedAt,
+      completed_at: null,
+      parent_execution_id: null,
+      error_message: null,
+      log_file: logFile,
+    })
+
+    // When dispatched as a workflow step, skip /execution-report in the prompt
+    // because the post-execution hook below handles completion reporting.
+    const isDispatchedStep = execution_id && step_index != null
+    const runOptions = isDispatchedStep ? { skipExecutionReport: true } : {}
+
+    // Run asynchronously — respond immediately
+    const executionPromise = (async () => {
+      let success = false
+      try {
+        const syntheticWorkflow = {
+          id: effectiveExecutionId,
+          name: workflow_name || skill_name,
+        }
+        const result = await workflowRunner.runWorkflow({
+          ...syntheticWorkflow,
+          pipeline_skill_names: skillNames,
+        }, runOptions)
+        success = !!result?.execution_id
+        return result
+      } catch (err) {
+        console.error(`[Skills] Run failed for ${skill_name}: ${err.message}`)
+        await executionStore.save({
+          id: effectiveExecutionId,
+          skill_name,
+          workflow_id: null,
+          workflow_name: workflow_name || null,
+          status: 'failed',
+          outcome: 'failure',
+          started_at: startedAt,
+          completed_at: new Date().toISOString(),
+          parent_execution_id: null,
+          error_message: err.message,
+          log_file: logFile,
+        })
+      } finally {
+        // Post-execution hook: report step completion to HQ
+        if (isDispatchedStep) {
+          try {
+            await api.reportStepComplete({
+              workflow_execution_id: execution_id,
+              step_index,
+              status: success ? 'completed' : 'failed',
+            })
+            console.log(`[Skills] Step completion reported: step ${step_index} → ${success ? 'completed' : 'failed'}`)
+          } catch (hookErr) {
+            console.error(`[Skills] Failed to report step completion: ${hookErr.message}`)
+          }
+        }
+      }
+    })()
+
+    executionPromise.catch(err => {
+      console.error(`[Skills] Unhandled error running ${skill_name}: ${err.message}`)
+    })
+
+    reply.code(202)
+    return {
+      success: true,
+      session_name: sessionName,
+      execution_id: effectiveExecutionId,
+      message: `Skill "${skill_name}" execution started`,
+    }
+  })
+
   // Delete a skill from local .claude/skills directory
   fastify.delete('/api/skills/:name', async (request, reply) => {
     if (!verifyToken(request)) {
@@ -299,7 +418,7 @@ async function skillRoutes(fastify) {
     console.log(`[Skills] Deleting skill: ${name}`)
 
     try {
-      const homeDir = os.homedir()
+      const homeDir = config.HOME_DIR
       const skillDir = path.join(homeDir, '.claude', 'skills', name)
 
       // Check if skill exists

package/routes/terminal.js

@@ -18,13 +18,13 @@ const { exec, spawn } = require('child_process')
 const { promisify } = require('util')
 const path = require('path')
 const net = require('net')
-const os = require('os')
 const execAsync = promisify(exec)
 
 const { verifyToken } = require('../lib/auth')
+const { config } = require('../config')
 
 // Ensure consistent HOME for tmux socket path
-const homeDir = os.homedir()
+const homeDir = config.HOME_DIR
 
 // ============================================================================
 // ttyd Process Management

package/routes/workflows.js

@@ -18,7 +18,6 @@
 
 const fs = require('fs').promises
 const path = require('path')
-const os = require('os')
 
 const { verifyToken } = require('../lib/auth')
 const workflowRunner = require('../workflow-runner')
@@ -26,7 +25,7 @@ const workflowStore = require('../workflow-store')
 const executionStore = require('../execution-store')
 const logManager = require('../lib/log-manager')
 const api = require('../api')
-const { isHqConfigured } = require('../config')
+const { config, isHqConfigured } = require('../config')
 const { writeSkillToLocal, pushSkillToHQ } = require('./skills')
 
 /**
@@ -214,7 +213,7 @@ async function workflowRoutes(fastify) {
 
       // 2. Fetch pipeline skills that are not deployed locally
       const fetchedSkills = []
-      const homeDir = os.homedir()
+      const homeDir = config.HOME_DIR
 
       for (const skillName of workflow.pipeline_skill_names || []) {
         const skillMdPath = path.join(homeDir, '.claude', 'skills', skillName, 'SKILL.md')

package/routine-runner.js

@@ -14,11 +14,11 @@ const { Cron } = require('croner')
 const { exec } = require('child_process')
 const { promisify } = require('util')
 const crypto = require('crypto')
-const os = require('os')
 const path = require('path')
 const fs = require('fs').promises
 const execAsync = promisify(exec)
 
+const { config } = require('./config')
 const executionStore = require('./execution-store')
 const routineStore = require('./routine-store')
 const logManager = require('./lib/log-manager')
@@ -92,7 +92,7 @@ async function cleanupMarkerFile(sessionName) {
  * @returns {Promise<{success: boolean, error?: string, sessionName?: string}>}
  */
 async function executeRoutineSession(routine, executionId, skillNames) {
-  const homeDir = os.homedir()
+  const homeDir = config.HOME_DIR
   const sessionName = generateSessionName(routine.id, executionId)
 
   // Build prompt: run each skill in sequence, then execution-report

package/routine-store.js

@@ -6,7 +6,8 @@
 
 const fs = require('fs').promises
 const path = require('path')
-const os = require('os')
+
+const { config } = require('./config')
 
 // Routine file location: /opt/minion-agent/routines.json (systemd/supervisord)
 // or ~/routines.json (standalone)
@@ -16,7 +17,7 @@ function getRoutineFilePath() {
     require('fs').accessSync(path.dirname(optPath))
     return optPath
   } catch {
-    return path.join(os.homedir(), 'routines.json')
+    return path.join(config.HOME_DIR, 'routines.json')
   }
 }
 

package/rules/minion.md

@@ -8,17 +8,45 @@ A local Agent API server runs at `http://localhost:3001` and a CLI tool `minion-
 ```
 Project (組織・課金単位)
 ├── Context (markdown, PMが更新)
-├── Members (minion + role)
-└── Workflows (何をするか, スケジュールなし)
+├── Members (minion + role: pm | engineer)
+└── Workflows (何をするか + オプションのcronスケジュール)
+    ├── Versions (pipeline の不変スナップショット)
+    └── Executions (実行履歴, ステップごとの進捗)
 
 Minion
-└── Routines (いつ・何を, cron付き)
+└── Routines (いつ・何を, cron付き, ミニオンローカルのタスク)
 ```
 
-- **Workflow** はプロジェクトスコープ。「何をするか」を定義。スケジュールは持たない。
-- **Routine** はミニオンスコープ。「いつ・何を」を定義。cron_expression を持ち、自律トリガーする。
+- **Workflow** はプロジェクトスコープ。バージョン管理されたパイプライン（スキル列）を持つ。オプションで `cron_expression` によるスケジュール実行が可能。HQ UIからワンショット実行もできる。
+- **Routine** はミニオンスコープ。ミニオンローカルの定期タスク。cron_expression を持ち自律トリガーする。
 - ミニオンは複数プロジェクトに `pm` または `engineer` として参加できる。
-- ワークフローは直接トリガーされず、ルーティン経由で実行される（`project-workflow-check` スキル）。
+- ワークフローの各ステップには `assigned_role`（pm/engineer）と `requires_review` フラグがある。
+
+## Workflow Execution Model (DB ステートマシン)
+
+ワークフロー実行はHQのDBがステートマシンとして管理する。ミニオン間通信は不要。
+
+```
+1. Execution 作成 (HQ UIのRunボタン or cronスケジュール)
+   → workflow_execution (status='pending')
+   → workflow_step_executions (全ステップ status='pending')
+
+2. ミニオンエージェントが GET /api/minion/pending-steps をポーリング
+   → 自分のロールに該当 & 前ステップ完了済みのステップを取得
+
+3. ミニオンがステップを実行し完了を報告
+   → POST /api/minion/execution で status/outcome を更新
+
+4. 次ステップが eligible に → 別のミニオンが検知して実行
+   → requires_review=true の場合はHQでレビュー承認後に次へ
+
+5. 全ステップ完了 → execution 全体を completed に
+```
+
+**ポイント:**
+- HQの責務は「executionレコードを作る（指示書発行）」だけ
+- 各ミニオンは自分の担当ステップだけをポーリングして実行
+- ミニオンエージェント（Port 3001）が軽量HTTPポーリングを行い、pending検知時のみClaude Codeを起動（トークン節約）
 
 ## CLI Commands
 
@@ -66,13 +94,9 @@ Authentication: `Authorization: Bearer $API_TOKEN` header (except where noted).
 | POST | `/api/workflows/push/:name` | Push local workflow to HQ |
 | POST | `/api/workflows/fetch/:name` | Fetch workflow from HQ and deploy locally (+ pipeline skills) |
 | GET | `/api/workflows/remote` | List workflows on HQ |
-| PUT | `/api/workflows/:id/schedule` | **Legacy.** Update cron_expression/is_active. 新アーキではRoutine側で管理 |
 | DELETE | `/api/workflows/:id` | Remove a local workflow |
 | POST | `/api/workflows/trigger` | Manual trigger. Body: `{workflow_id}` |
 
-> **Note:** 新アーキテクチャでは Workflow にスケジュールがなく、Routine の cron で自律トリガーする設計。
-> `PUT /api/workflows/:id/schedule` はレガシー互換で残っているが、新規利用は非推奨。
-
 ### Executions
 
 | Method | Endpoint | Description |
@@ -156,20 +180,34 @@ Response:
 
 PUT body: `{ "content": "markdown string" }`
 
-### Workflows (project-scoped)
+### Workflows (project-scoped, versioned)
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/minion/workflows` | 参加プロジェクトのワークフロー一覧 |
+| GET | `/api/minion/workflows` | 参加プロジェクトのアクティブなワークフロー一覧 |
+| POST | `/api/minion/workflows` | ワークフローを push（新規作成 or 新バージョン） |
 
-Response:
+GET Response:
 ```json
 {
   "workflows": [
     {
-      "name": "workflow-name",
+      "name": "daily-check",
       "pipeline_skill_names": ["skill-1", "skill-2"],
+      "pipeline": [
+        {
+          "skill_version_id": "uuid",
+          "skill_name": "skill-1",
+          "skill_display_name": "Skill One",
+          "skill_version": 3,
+          "assigned_role": "engineer",
+          "requires_review": false,
+          "is_my_step": true
+        }
+      ],
       "content": "...",
+      "version": 3,
+      "cron_expression": "0 9 * * *",
       "project_id": "uuid",
       "created_at": "..."
     }
@@ -177,6 +215,122 @@ Response:
 }
 ```
 
+各ステップの `is_my_step` はミニオン自身のプロジェクトロールと `assigned_role` の一致を示す。
+
+POST body (push):
+```json
+{
+  "name": "my-workflow",
+  "pipeline_skill_names": ["skill-1", "skill-2"],
+  "content": "Workflow description",
+  "project_id": "uuid",
+  "change_summary": "Added skill-2 to pipeline"
+}
+```
+
+push するとパイプライン内のスキル名が `skill_version_id` に解決され、新バージョンが自動作成される。
+
+### Pending Steps (軽量ポーリング)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/pending-steps` | 自分が実行すべき pending ステップ一覧 |
+
+**このエンドポイントはミニオンエージェント（非AI）による高頻度ポーリング用。**
+Claude Code（AIスキル実行）はステップ検知時のみ起動する。
+
+Response:
+```json
+{
+  "steps": [
+    {
+      "step_execution_id": "uuid",
+      "execution_id": "uuid",
+      "workflow_name": "daily-check",
+      "step_index": 0,
+      "skill_version_id": "uuid",
+      "assigned_role": "engineer"
+    }
+  ]
+}
+```
+
+返却条件:
+- `assigned_role` がミニオンのプロジェクトロールと一致
+- ステップの `status` が `pending`
+- 前ステップが全て `completed`（`requires_review` の場合は `approved` も必要）
+
+### Workflow Execution Recording
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/minion/workflow-execution` | 新規 execution 開始を記録 |
+| POST | `/api/minion/execution` | ステップ実行状況を HQ に報告 |
+
+POST `/api/minion/workflow-execution` body:
+```json
+{
+  "workflow_version_id": "uuid"
+}
+```
+
+Response:
+```json
+{
+  "execution_id": "uuid",
+  "status": "running",
+  "steps_count": 3
+}
+```
+
+POST `/api/minion/execution` body:
+```json
+{
+  "workflow_execution_id": "uuid",
+  "steps": [
+    {
+      "step_index": 0,
+      "skill_version_id": "uuid",
+      "assigned_role": "engineer",
+      "status": "completed",
+      "outcome": "success",
+      "started_at": "...",
+      "completed_at": "..."
+    }
+  ],
+  "status": "running",
+  "started_at": "..."
+}
+```
+
+### Issue Reporting (GitHub Issue 起票)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/minion/report` | バグや改善提案を GitHub Issue として起票 |
+
+POST `/api/minion/report` body:
+```json
+{
+  "title": "HQ APIで502エラーが発生する",
+  "body": "## 状況\n...\n\n## 再現手順\n...\n\n## エラー情報\n...\n\n## 環境\n...",
+  "labels": ["bug", "critical"]
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "issue_url": "https://github.com/owner/repo/issues/42",
+  "issue_number": 42
+}
+```
+
+使用可能なラベル: `bug`, `enhancement`, `critical`, `minor`
+
+**使い方:** サービスのバグや改善点を発見したら、このエンドポイントで GitHub Issue を起票する。報告者のミニオン名と ID が自動で本文に付記される。
+
 ### Routines (minion-scoped)
 
 | Method | Endpoint | Description |
@@ -206,14 +360,10 @@ Response:
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/minion/skills` | HQ に登録されたスキル一覧 |
-| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, references 含む） |
-| POST | `/api/minion/skills` | スキル登録/更新 |
+| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, files 含む） |
+| POST | `/api/minion/skills` | スキル登録/更新（新バージョン自動作成） |
 
-### Execution Reporting
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/api/minion/execution` | 実行状況を HQ に報告 |
+スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。
 
 ## Environment Variables
 
@@ -254,27 +404,53 @@ When not configured, the agent runs in standalone mode and HQ-dependent features
 
 ## Workflow Structure
 
-Workflows are project-scoped and fetched from HQ via `GET /api/minion/workflows`.
-They are also stored locally in `workflows.json`. Each workflow object:
+Workflows are project-scoped and versioned. Each version is an immutable snapshot of the pipeline.
+Fetched from HQ via `GET /api/minion/workflows`. Also stored locally in `workflows.json`.
 
 ```json
 {
-  "id": "uuid",
   "name": "my-workflow",
   "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
+  "pipeline": [
+    {
+      "skill_version_id": "uuid",
+      "skill_name": "skill-1",
+      "skill_display_name": "Skill One",
+      "skill_version": 2,
+      "assigned_role": "engineer",
+      "requires_review": false,
+      "is_my_step": true
+    }
+  ],
   "content": "Markdown description of the workflow",
+  "version": 2,
+  "cron_expression": "0 9 * * *",
   "project_id": "uuid"
 }
 ```
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | string | UUID (auto-generated) |
 | `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
-| `pipeline_skill_names` | string[] | Ordered skill names to execute |
+| `pipeline_skill_names` | string[] | Ordered skill names (for display/push) |
+| `pipeline` | PipelineStep[] | Resolved pipeline with version IDs and roles |
 | `content` | string | Markdown body describing the workflow |
+| `version` | number | Current version number (auto-incremented on push) |
+| `cron_expression` | string\|null | Cron schedule (null = manual/one-shot only) |
 | `project_id` | string | UUID of the parent project |
 
+### Pipeline Step Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `skill_version_id` | string | UUID of the specific skill version |
+| `skill_name` | string | Skill slug name |
+| `skill_display_name` | string | Human-readable skill name |
+| `skill_version` | number | Skill version number |
+| `assigned_role` | string | `"pm"` or `"engineer"` — who executes this step |
+| `requires_review` | boolean | If true, human review required after completion |
+| `is_my_step` | boolean | Whether this minion's role matches assigned_role |
+
 ### Syncing workflows with HQ
 
 - `POST /api/workflows/push/:name` — Push local workflow to HQ. Pipeline skills are auto-pushed first.
@@ -320,9 +496,27 @@ Routines run on cron schedules. Each execution:
 3. Appends `execution-report` skill to report outcome
 4. Environment variables `MINION_EXECUTION_ID`, `MINION_ROUTINE_ID`, `MINION_ROUTINE_NAME` are available during execution
 
-### Workflow Execution via Routine
+## Workflow Step Execution via Pending Steps
+
+ミニオンエージェントは `GET /api/minion/pending-steps` を定期ポーリングし、
+自分の担当ステップを検知したら Claude Code を起動してスキルを実行する。
+
+```
+ミニオンエージェント (Port 3001, 常駐, トークン不要)
+  │
+  ├── 軽量ポーリング: N秒ごとに GET /api/minion/pending-steps
+  │   → HTTPのみ、AIなし、コストゼロ
+  │   → pendingステップがなければ何もしない
+  │
+  └── ステップ検知時のみ:
+      1. Claude Code 起動 → 該当スキルを実行
+      2. POST /api/minion/execution → ステップ完了を報告
+      3. Claude Code 終了 → トークン消費はここだけ
+```
+
+### Workflow Execution via Routine (従来方式)
 
-ワークフローは `project-workflow-check` システムスキルを通じてルーティンから実行される:
+ワークフローは `project-workflow-check` システムスキルを通じてルーティンからも実行可能:
 
 ```
 ルーティン: "morning-work" (cron: 0 9 * * 1-5)

package/server.js

@@ -7,7 +7,6 @@
 
 const fs = require('fs')
 const path = require('path')
-const os = require('os')
 
 const fastify = require('fastify')({ logger: true })
 const { config, validate, isHqConfigured } = require('./config')
@@ -56,7 +55,7 @@ process.on('SIGINT', () => shutdown('SIGINT'))
  */
 function syncPermissions() {
   const bundledPath = path.join(__dirname, 'settings', 'permissions.json')
-  const settingsDir = path.join(os.homedir(), '.claude')
+  const settingsDir = path.join(config.HOME_DIR, '.claude')
   const settingsPath = path.join(settingsDir, 'settings.json')
 
   try {
@@ -90,7 +89,7 @@ function syncPermissions() {
  */
 function syncTmuxConfig() {
   const bundledPath = path.join(__dirname, 'settings', 'tmux.conf')
-  const destPath = path.join(os.homedir(), '.tmux.conf')
+  const destPath = path.join(config.HOME_DIR, '.tmux.conf')
 
   try {
     if (!fs.existsSync(bundledPath)) return
@@ -108,7 +107,7 @@ function syncTmuxConfig() {
  */
 function syncBundledRules() {
   const bundledRulesDir = path.join(__dirname, 'rules')
-  const targetRulesDir = path.join(os.homedir(), '.claude', 'rules')
+  const targetRulesDir = path.join(config.HOME_DIR, '.claude', 'rules')
 
   try {
     if (!fs.existsSync(bundledRulesDir)) return

package/settings/permissions.json

@@ -4,6 +4,8 @@
     "Read",
     "Write",
     "Edit",
+    "WebSearch",
+    "WebFetch",
     "mcp__playwright__*"
   ],
   "deny": [

package/workflow-runner.js

@@ -14,11 +14,11 @@ const { Cron } = require('croner')
 const { exec } = require('child_process')
 const { promisify } = require('util')
 const crypto = require('crypto')
-const os = require('os')
 const path = require('path')
 const fs = require('fs').promises
 const execAsync = promisify(exec)
 
+const { config } = require('./config')
 const executionStore = require('./execution-store')
 const workflowStore = require('./workflow-store')
 const logManager = require('./lib/log-manager')
@@ -90,13 +90,17 @@ async function cleanupMarkerFile(sessionName) {
  * @param {object} workflow - Workflow configuration
  * @returns {Promise<{success: boolean, error?: string, sessionName?: string}>}
  */
-async function executeWorkflowSession(workflow, executionId, skillNames) {
-  const homeDir = os.homedir()
+async function executeWorkflowSession(workflow, executionId, skillNames, options = {}) {
+  const homeDir = config.HOME_DIR
   const sessionName = generateSessionName(workflow.id, executionId)
 
-  // Build prompt: run each skill in sequence, then execution-report
+  // Build prompt: run each skill in sequence
+  // When skipExecutionReport is true (dispatched step), the minion server's
+  // post-execution hook handles completion reporting instead of /execution-report.
   const skillCommands = skillNames.map(name => `/${name}`).join(', then ')
-  const prompt = `Run the following skills in order: ${skillCommands}. After completing all skills, run /execution-report to report the results.`
+  const prompt = options.skipExecutionReport
+    ? `Run the following skills in order: ${skillCommands}.`
+    : `Run the following skills in order: ${skillCommands}. After completing all skills, run /execution-report to report the results.`
 
   // Extend PATH to include common CLI installation locations
   const additionalPaths = [
@@ -187,11 +191,10 @@ async function executeWorkflowSession(workflow, executionId, skillNames) {
 
     while (Date.now() - startTime < timeout) {
       try {
-        await execAsync(`tmux has-session -t "${sessionName}" 2>/dev/null`)
-        await sleep(pollInterval)
+        await fs.access(exitCodeFile)
+        break // Exit code file exists — claude -p has finished
       } catch {
-        // Session ended
-        break
+        await sleep(pollInterval)
       }
     }
 
@@ -245,7 +248,7 @@ async function saveExecution(executionData) {
  * @param {object} workflow - Workflow configuration
  * @returns {Promise<{execution_id: string, session_name: string}>}
  */
-async function runWorkflow(workflow) {
+async function runWorkflow(workflow, options = {}) {
   const pipelineSkillNames = workflow.pipeline_skill_names || []
 
   if (pipelineSkillNames.length === 0) {
@@ -285,7 +288,7 @@ async function runWorkflow(workflow) {
   })
 
   // Execute all skills in one session
-  const result = await executeWorkflowSession(workflow, executionId, pipelineSkillNames)
+  const result = await executeWorkflowSession(workflow, executionId, pipelineSkillNames, options)
 
   const completedAt = new Date().toISOString()
   console.log(`[WorkflowRunner] executeWorkflowSession returned: success=${result.success}, error=${result.error || 'none'}`)

package/workflow-store.js

@@ -6,7 +6,8 @@
 
 const fs = require('fs').promises
 const path = require('path')
-const os = require('os')
+
+const { config } = require('./config')
 
 // Workflow file location: /opt/minion-agent/workflows.json (systemd/supervisord)
 // or ~/workflows.json (standalone)
@@ -17,7 +18,7 @@ function getWorkflowFilePath() {
     require('fs').accessSync(path.dirname(optPath))
     return optPath
   } catch {
-    return path.join(os.homedir(), 'workflows.json')
+    return path.join(config.HOME_DIR, 'workflows.json')
   }
 }