@geekbeer/minion 3.51.1 → 3.52.0

package/core/api.js

@@ -6,6 +6,16 @@
  */
 
 const { config, isHqConfigured } = require('./config')
+const frozenState = require('./lib/frozen-state')
+
+class BillingFrozenError extends Error {
+  constructor(reason) {
+    super(`Minion is billing-frozen: ${reason || 'unknown'}`)
+    this.name = 'BillingFrozenError'
+    this.statusCode = 402
+    this.billingFrozen = true
+  }
+}
 
 /**
  * Send HTTP request to the HQ server
@@ -17,6 +27,10 @@ async function request(endpoint, options = {}) {
     return { skipped: true, reason: 'HQ not configured' }
   }
 
+  if (frozenState.isFrozen()) {
+    throw new BillingFrozenError(frozenState.getState().reason)
+  }
+
   const url = `${config.HQ_URL}/api/minion${endpoint}`
 
   const response = await fetch(url, {
@@ -28,10 +42,19 @@ async function request(endpoint, options = {}) {
     },
   })
 
-  const data = await response.json()
+  let data = null
+  try {
+    data = await response.json()
+  } catch {
+    data = {}
+  }
+
+  if (frozenState.maybeFreezeFromResponse(response, data)) {
+    throw new BillingFrozenError(data && data.reason)
+  }
 
   if (!response.ok) {
-    const err = new Error(data.error || `API request failed: ${response.status}`)
+    const err = new Error((data && data.error) || `API request failed: ${response.status}`)
     err.statusCode = response.status
     throw err
   }
@@ -203,4 +226,5 @@ module.exports = {
   deleteThread,
   createProjectMemory,
   searchProjectMemories,
+  BillingFrozenError,
 }

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

@@ -21,6 +21,8 @@
 
 const { config, isHqConfigured } = require('../config')
 const concurrency = require('./concurrency-manager')
+const frozenState = require('./frozen-state')
+const api = require('../api')
 
 // Polling interval: 30 seconds (matches dag-step-poller).
 const POLL_INTERVAL_MS = 30_000
@@ -45,6 +47,9 @@ async function hqRequest(endpoint, options = {}) {
   if (!isHqConfigured()) {
     return { skipped: true, reason: 'HQ not configured' }
   }
+  if (frozenState.isFrozen()) {
+    throw new api.BillingFrozenError(frozenState.getState().reason)
+  }
   const url = `${config.HQ_URL}${endpoint}`
   const resp = await fetch(url, {
     ...options,
@@ -61,6 +66,9 @@ async function hqRequest(endpoint, options = {}) {
   } catch {
     data = { raw: text }
   }
+  if (frozenState.maybeFreezeFromResponse(resp, data)) {
+    throw new api.BillingFrozenError(data && data.reason)
+  }
   if (!resp.ok) {
     const err = new Error(data.error || `HQ ${endpoint} failed: ${resp.status}`)
     err.statusCode = resp.status
@@ -72,6 +80,7 @@ async function hqRequest(endpoint, options = {}) {
 
 async function pollOnce() {
   if (!isHqConfigured()) return
+  if (frozenState.isFrozen()) return
   if (!runner) {
     console.warn('[BoardTaskPoller] No runner injected, skipping poll')
     return
@@ -117,7 +126,9 @@ async function pollOnce() {
         })
     }
   } catch (err) {
-    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+    if (err.billingFrozen) {
+      console.log('[BoardTaskPoller] Billing frozen, suspending poll')
+    } else 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}`)

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

@@ -12,6 +12,8 @@
  */
 
 const { config, isHqConfigured } = require('../config')
+const frozenState = require('./frozen-state')
+const api = require('../api')
 
 const POLL_INTERVAL_MS = 60_000
 
@@ -22,6 +24,7 @@ let lastFiredCount = 0
 
 async function pollOnce() {
   if (!isHqConfigured()) return
+  if (frozenState.isFrozen()) return
   if (polling) return
 
   polling = true
@@ -35,6 +38,14 @@ async function pollOnce() {
       },
     })
 
+    let payload = null
+    if (resp.status === 402) {
+      try { payload = await resp.json() } catch { payload = {} }
+      if (frozenState.maybeFreezeFromResponse(resp, payload)) {
+        throw new api.BillingFrozenError(payload && payload.reason)
+      }
+    }
+
     if (!resp.ok) {
       throw new Error(`dag-cron-tick failed: ${resp.status}`)
     }
@@ -58,7 +69,9 @@ async function pollOnce() {
       }
     }
   } catch (err) {
-    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+    if (err.billingFrozen) {
+      console.log('[DagCronPoller] Billing frozen, suspending poll')
+    } else if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
       console.log('[DagCronPoller] HQ unreachable, will retry next cycle')
     } else {
       console.error(`[DagCronPoller] Poll error: ${err.message}`)

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

@@ -13,6 +13,7 @@ const { config, isHqConfigured } = require('../config')
 const api = require('../api')
 const variableStore = require('../stores/variable-store')
 const concurrency = require('./concurrency-manager')
+const frozenState = require('./frozen-state')
 
 // Polling interval: 30 seconds (matches step-poller)
 const POLL_INTERVAL_MS = 30_000
@@ -38,6 +39,10 @@ async function dagRequest(endpoint, options = {}) {
     return { skipped: true, reason: 'HQ not configured' }
   }
 
+  if (frozenState.isFrozen()) {
+    throw new api.BillingFrozenError(frozenState.getState().reason)
+  }
+
   const url = `${config.HQ_URL}/api/dag/minion${endpoint}`
   const resp = await fetch(url, {
     ...options,
@@ -48,6 +53,14 @@ async function dagRequest(endpoint, options = {}) {
     },
   })
 
+  let payload = null
+  if (resp.status === 402) {
+    try { payload = await resp.json() } catch { payload = {} }
+    if (frozenState.maybeFreezeFromResponse(resp, payload)) {
+      throw new api.BillingFrozenError(payload && payload.reason)
+    }
+  }
+
   if (!resp.ok) {
     const err = new Error(`DAG API ${endpoint} failed: ${resp.status}`)
     err.statusCode = resp.status
@@ -62,6 +75,7 @@ async function dagRequest(endpoint, options = {}) {
  */
 async function pollOnce() {
   if (!isHqConfigured()) return
+  if (frozenState.isFrozen()) return
   if (polling) return
 
   polling = true
@@ -90,7 +104,9 @@ async function pollOnce() {
       promise
     }
   } catch (err) {
-    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+    if (err.billingFrozen) {
+      console.log('[DagPoller] Billing frozen, suspending poll')
+    } else if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
       console.log('[DagPoller] HQ unreachable, will retry next cycle')
     } else {
       console.error(`[DagPoller] Poll error: ${err.message}`)

package/core/lib/frozen-state.js

@@ -0,0 +1,64 @@
+/**
+ * Frozen State Module
+ *
+ * Tracks billing-driven freeze state in-memory. When frozen, all pollers
+ * skip their work and the shared HTTP wrappers refuse outbound calls.
+ *
+ * State is intentionally NOT persisted to disk:
+ * - Recovery is driven by HQ pushing `restart-agent` after payment success.
+ * - Process restart naturally clears the in-memory flag.
+ * - On restart, if billing is still past_due, the next request will receive
+ *   402 from HQ and self-freeze again. Self-healing.
+ */
+
+let frozen = false
+let frozenAt = null
+let reason = null
+
+function isFrozen() {
+  return frozen
+}
+
+function setFrozen(opts = {}) {
+  if (frozen) return
+  frozen = true
+  frozenAt = new Date().toISOString()
+  reason = opts.reason || 'unknown'
+  console.log(`[FrozenState] Minion frozen: reason=${reason} at=${frozenAt}`)
+}
+
+function clearFrozen() {
+  if (!frozen) return
+  frozen = false
+  frozenAt = null
+  reason = null
+  console.log('[FrozenState] Minion unfrozen (in-memory state cleared)')
+}
+
+function getState() {
+  return { frozen, frozenAt, reason }
+}
+
+/**
+ * Inspect a fetch Response for the 402 billing-frozen signal and
+ * self-freeze if matched. Returns true if frozen was set.
+ *
+ * Expected payload: `{ "error": "billing_frozen", "reason": "past_due", ... }`
+ */
+function maybeFreezeFromResponse(response, payload) {
+  if (response && response.status === 402) {
+    if (payload && payload.error === 'billing_frozen') {
+      setFrozen({ reason: payload.reason || 'billing_frozen' })
+      return true
+    }
+  }
+  return false
+}
+
+module.exports = {
+  isFrozen,
+  setFrozen,
+  clearFrozen,
+  getState,
+  maybeFreezeFromResponse,
+}

package/core/lib/revision-watcher.js

@@ -15,6 +15,7 @@
 
 const { config, isHqConfigured } = require('../config')
 const api = require('../api')
+const frozenState = require('./frozen-state')
 
 // Poll every 30 seconds (same frequency as step-poller)
 const POLL_INTERVAL_MS = 30_000
@@ -33,6 +34,7 @@ const processingRevisions = new Set()
  */
 async function pollOnce() {
   if (!isHqConfigured()) return
+  if (frozenState.isFrozen()) return
   if (polling) return
 
   polling = true
@@ -59,7 +61,9 @@ async function pollOnce() {
       }
     }
   } catch (err) {
-    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+    if (err.billingFrozen) {
+      console.log(`[RevisionWatcher] Billing frozen, suspending poll`)
+    } else if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
       console.log(`[RevisionWatcher] HQ unreachable, will retry next cycle`)
     } else {
       console.error(`[RevisionWatcher] Poll error: ${err.message}`)

package/core/lib/step-poller.js

@@ -21,6 +21,7 @@
 const { config, isHqConfigured } = require('../config')
 const api = require('../api')
 const variableStore = require('../stores/variable-store')
+const frozenState = require('./frozen-state')
 
 // Polling interval: 30 seconds (matches heartbeat frequency)
 const POLL_INTERVAL_MS = 30_000
@@ -42,6 +43,7 @@ let lastPollAt = null
  */
 async function pollOnce() {
   if (!isHqConfigured()) return
+  if (frozenState.isFrozen()) return
   if (polling) return
 
   polling = true
@@ -70,7 +72,9 @@ async function pollOnce() {
     }
   } catch (err) {
     // Don't log network errors at error level — they're expected when HQ is temporarily unreachable
-    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+    if (err.billingFrozen) {
+      console.log(`[StepPoller] Billing frozen, suspending poll`)
+    } else if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
       console.log(`[StepPoller] HQ unreachable, will retry next cycle`)
     } else {
       console.error(`[StepPoller] Poll error: ${err.message}`)

package/core/lib/thread-watcher.js

@@ -20,6 +20,7 @@
 
 const { config, isHqConfigured, isLlmConfigured } = require('../config')
 const api = require('../api')
+const frozenState = require('./frozen-state')
 
 // Poll every 15 seconds
 const POLL_INTERVAL_MS = 15_000
@@ -94,6 +95,7 @@ function isMentioned(thread, messages, myRole) {
  */
 async function pollOnce() {
   if (!isHqConfigured()) return
+  if (frozenState.isFrozen()) return
   if (polling) return
 
   polling = true
@@ -115,7 +117,9 @@ async function pollOnce() {
       }
     }
   } catch (err) {
-    if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+    if (err.billingFrozen) {
+      // Billing frozen — silent
+    } else if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
       // HQ unreachable — silent retry
     } else {
       console.error(`[ThreadWatcher] Poll error: ${err.message}`)

package/core/routes/admin.js

@@ -0,0 +1,49 @@
+/**
+ * Admin routes
+ *
+ * HQ-only operations pushed via Cloudflare Tunnel. Currently exposes the
+ * billing-driven freeze endpoint. Recovery is intentionally NOT exposed
+ * here — HQ recovers a frozen minion by sending the existing
+ * `restart-agent` command (commands.js), which terminates the process and
+ * lets the in-memory frozen flag clear naturally.
+ *
+ * Endpoints:
+ *   POST /api/admin/freeze   - Set in-memory frozen state
+ *   GET  /api/admin/state    - Diagnostic: report frozen state
+ */
+
+const { verifyToken } = require('../lib/auth')
+const frozenState = require('../lib/frozen-state')
+
+async function adminRoutes(fastify) {
+  fastify.post('/api/admin/freeze', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const body = request.body || {}
+    const reason = typeof body.reason === 'string' ? body.reason : 'past_due'
+
+    frozenState.setFrozen({ reason })
+
+    return {
+      success: true,
+      state: frozenState.getState(),
+    }
+  })
+
+  fastify.get('/api/admin/state', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    return {
+      success: true,
+      state: frozenState.getState(),
+    }
+  })
+}
+
+module.exports = { adminRoutes }

package/docs/api-reference.md

@@ -705,6 +705,23 @@ Note: 既読メールは受信後90日で自動削除される。未読メール
 
 Available commands: `restart-agent`, `update-agent`, `restart-display`, `restart-all`, `status-services`
 
+### Admin (HQ → Minion only)
+
+HQ が課金状態の変化に応じてミニオンに直接プッシュするエンドポイント。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/admin/freeze` | ポーラーを停止しHQへの発信を抑止する。Body: `{reason}` |
+| GET  | `/api/admin/state`  | 現在のfrozen状態を取得 |
+
+**Freeze の挙動 (v3.52.0〜):**
+- ミニオン内のグローバル `frozen=true` (in-memory only) を立てる。
+- 各ポーラー (step, dag-step, board-task, thread-watcher, dag-cron, revision-watcher, heartbeat) が `pollOnce()` 直前で `isFrozen()` を確認しスキップ。
+- 共通HTTPクライアント (`core/api.js`, 各pollerの `*Request`) は HQ から `402 billing_frozen` を受信した時点で自動的に `frozen=true` をセット (HQからのpushが届かなくても自己防衛)。
+- 状態は**ディスク永続化されない**。プロセス再起動で自動的にクリアされ、課金復活後の `restart-agent` コマンドで自然に解除される。
+
+復旧は HQ が既存の `POST /api/command { command: "restart-agent" }` をプッシュすることで行う (専用 unfreeze エンドポイントは無い)。
+
 ---
 
 ## HQ API Endpoints (https://<HQ_URL>)
@@ -1337,7 +1354,7 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 |------|---------------|------|
 | `start` / `end` | なし | |
 | `skill` | `skill_id`, `skill_version_id`, `assigned_role` | |
-| `review` | `review: { reviewer_type, criteria, revision_target }` | `revision` エッジと `approved` エッジが**自動生成**される |
+| `review` | `assigned_role`, `review: { criteria, revision_target }` | `assigned_role: 'human'` でダッシュボードからの人間レビュー、`'pm'`/`'engineer'`/`'accountant'` で将来の minion レビュー枠（現在は未実装、`waiting` で停止）。`revision` / `approved` エッジは自動生成 |
 | `fan_out` | `fan_out_source`, `template` | `template` は sub-graph `{ nodes, edges }` |
 | `join` | `join_mode`, `aggregation` | |
 | `conditional` | `condition_type`, `branches` or `default_branch` | |
@@ -1350,13 +1367,24 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
   "label": "Quality Check",
   "after": "skill_1",
   "before": "end",
+  "assigned_role": "human",
   "review": {
-    "reviewer_type": "human",
     "criteria": "成果物の品質を確認",
-    "revision_target": "skill_1"
+    "revision_target": "skill_1",
+    "preferred_reviewer_id": "<user UUID（任意・指定なしの場合は全プロジェクトメンバーに通知）>"
   }
 }
 ```
+
+`assigned_role` の値:
+- `human` — ダッシュボードから人間が承認 (`workflow.review_requested` 通知が送信される)
+- `pm` / `engineer` / `accountant` — 将来の minion レビュー枠 (現在は未実装、`waiting` で停止)
+
+`preferred_reviewer_id` (任意):
+- `assigned_role === 'human'` の場合: `profiles.user_id` を指定すると通知をその人に絞る。脱退済みなら全メンバーにフォールバック
+- `assigned_role !== 'human'` の場合: `minions.id` を指定（現在は未実装）
+
+> 互換性: 旧形式 `review: { reviewer_type, reviewer_id }` も読み取り可能ですが、新規作成時は `assigned_role` + `preferred_reviewer_id` を使ってください。
 → `skill_1 → end` のエッジが削除され、以下が自動生成:
 - `skill_1 → review_1` (normal)
 - `review_1 → end` (approved)

package/docs/task-guides.md

@@ -309,8 +309,8 @@ cat > /tmp/n.json <<'EOF'
   "label": "Quality Check",
   "after": "skill_1",
   "before": "end_1",
+  "assigned_role": "human",
   "review": {
-    "reviewer_type": "human",
     "criteria": "成果物の品質を確認",
     "revision_target": "skill_1"
   }

package/linux/server.js

@@ -74,6 +74,7 @@ const { skillRoutes } = require('../core/routes/skills')
 const { workflowRoutes } = require('../core/routes/workflows')
 const { routineRoutes } = require('../core/routes/routines')
 const { authRoutes } = require('../core/routes/auth')
+const { adminRoutes } = require('../core/routes/admin')
 const { variableRoutes } = require('../core/routes/variables')
 const { memoryRoutes } = require('../core/routes/memory')
 const { dailyLogRoutes } = require('../core/routes/daily-logs')
@@ -286,6 +287,7 @@ async function registerAllRoutes(app) {
   await app.register(workflowRoutes, { workflowRunner })
   await app.register(routineRoutes, { routineRunner })
   await app.register(authRoutes)
+  await app.register(adminRoutes)
   await app.register(variableRoutes)
   await app.register(memoryRoutes)
   await app.register(dailyLogRoutes)

package/package.json

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

package/rules/core.md

@@ -103,7 +103,15 @@ minion-cli --version                      # バージョン確認
 
 `http://localhost:8080` — 認証: `Authorization: Bearer $API_TOKEN`
 
-主なカテゴリ: Health, Skills, Workflows, Executions, Terminal, Files, Commands, Permissions
+主なカテゴリ: Health, Skills, Workflows, Executions, Terminal, Files, Commands, Permissions, Admin (HQ-pushed freeze)
+
+#### Billing-Driven Freeze (v3.52.0〜)
+
+ユーザーの決済が `past_due` に陥ると、HQ から `POST /api/admin/freeze` がプッシュされ、ミニオン全ポーラーが停止する。
+- 状態は in-memory のみ (frozen.json などのディスクファイルは存在しない)。
+- HQ への発信中に `402 billing_frozen` を受けた場合も自動的にfrozen化される (HQ pushが届かなくても自己防衛)。
+- 復旧は HQ が `restart-agent` コマンドをプッシュ → プロセス再起動 → in-memory フラグが消えて自動再開。
+- API仕様は `~/.minion/docs/api-reference.md` の「Admin」セクション参照。
 
 #### Permission Management
 

package/win/server.js

@@ -57,6 +57,7 @@ const { skillRoutes } = require('../core/routes/skills')
 const { workflowRoutes } = require('../core/routes/workflows')
 const { routineRoutes } = require('../core/routes/routines')
 const { authRoutes } = require('../core/routes/auth')
+const { adminRoutes } = require('../core/routes/admin')
 const { variableRoutes } = require('../core/routes/variables')
 const { memoryRoutes } = require('../core/routes/memory')
 const { dailyLogRoutes } = require('../core/routes/daily-logs')
@@ -221,6 +222,7 @@ async function registerRoutes(app) {
   await app.register(workflowRoutes, { workflowRunner })
   await app.register(routineRoutes, { routineRunner })
   await app.register(authRoutes)
+  await app.register(adminRoutes)
   await app.register(variableRoutes)
   await app.register(memoryRoutes)
   await app.register(dailyLogRoutes)