idlewatch 0.1.0

package/scripts/validate-packaged-usage-recovery-e2e.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, chmodSync, rmSync, readFileSync } from 'node:fs'
+import { readTelemetryJsonRow } from './lib/telemetry-row-parser.mjs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const repoRoot = process.cwd()
+const appBin = './dist/IdleWatch.app/Contents/MacOS/IdleWatch'
+const tempDir = mkdtempSync(join(tmpdir(), 'idlewatch-packaged-recovery-'))
+const mockBinPath = join(tempDir, 'openclaw-mock.sh')
+const counterPath = join(tempDir, 'counter.txt')
+
+function writeMockOpenClaw(binPath, callCounterPath) {
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+counter_file="${callCounterPath}"
+if [[ ! -f "$counter_file" ]]; then
+  echo 0 > "$counter_file"
+fi
+n=$(cat "$counter_file")
+next=$((n + 1))
+echo "$next" > "$counter_file"
+
+# First call returns post-threshold age, second call returns fresh age.
+if [[ "$n" -eq 0 ]]; then
+  age_ms=65000
+else
+  age_ms=2000
+fi
+
+now_ms=$(node -p 'Date.now()')
+updated_at=$((now_ms - age_ms))
+cat <<JSON
+{"sessions":{"defaults":{"model":"gpt-5.3-codex"},"recent":[{"sessionId":"sess-packaged-recovery","agentId":"main","model":"gpt-5.3-codex","totalTokens":99999,"updatedAt":\${updated_at},"totalTokensFresh":true}]},"ts":\${now_ms}}
+JSON
+`
+  writeFileSync(binPath, script, 'utf8')
+  chmodSync(binPath, 0o755)
+}
+
+function readRow(output) {
+  return readTelemetryJsonRow(output)
+}
+
+try {
+  writeMockOpenClaw(mockBinPath, counterPath)
+
+  if (process.env.IDLEWATCH_SKIP_PACKAGE_MACOS !== '1') {
+    execFileSync('npm', ['run', 'package:macos', '--silent'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+  }
+
+  const env = {
+    ...process.env,
+    IDLEWATCH_OPENCLAW_BIN: mockBinPath,
+    IDLEWATCH_USAGE_STALE_MS: '60000',
+    IDLEWATCH_USAGE_STALE_GRACE_MS: '10000',
+    IDLEWATCH_USAGE_REFRESH_REPROBES: '1',
+    IDLEWATCH_USAGE_REFRESH_DELAY_MS: '0',
+    IDLEWATCH_INTERVAL_MS: '1000'
+  }
+
+  const out = execFileSync(appBin, ['--dry-run'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  const row = readRow(out)
+  assert.equal(row?.source?.usageIngestionStatus, 'ok')
+  assert.equal(row?.source?.usageRefreshAttempted, true)
+  assert.equal(row?.source?.usageRefreshRecovered, true)
+  assert.ok((row?.source?.usageRefreshAttempts ?? 0) >= 1, 'expected at least one refresh attempt during recovery pass')
+  assert.equal(row?.source?.usageActivityStatus, 'fresh')
+  assert.equal(row?.source?.usageAlertLevel, 'ok')
+  assert.equal(row?.source?.usageAlertReason, 'healthy')
+
+  const probeCalls = Number(readFileSync(counterPath, 'utf8').trim())
+  assert.ok(probeCalls >= 2, `expected mock OpenClaw to be invoked >=2 times, got ${probeCalls}`)
+
+  console.log('packaged-usage-recovery-e2e: ok (post-threshold sample recovered to fresh via forced reprobe)')
+} finally {
+  rmSync(tempDir, { recursive: true, force: true })
+}

package/scripts/validate-trusted-prereqs.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CODESIGN_IDENTITY="${MACOS_CODESIGN_IDENTITY:-}"
+NOTARY_PROFILE="${MACOS_NOTARY_PROFILE:-}"
+
+if [[ -z "$CODESIGN_IDENTITY" ]]; then
+  echo "Missing MACOS_CODESIGN_IDENTITY. Example: Developer ID Application: Your Name (TEAMID)" >&2
+  exit 1
+fi
+
+if [[ -z "$NOTARY_PROFILE" ]]; then
+  echo "Missing MACOS_NOTARY_PROFILE. Create one with: xcrun notarytool store-credentials <profile> ..." >&2
+  exit 1
+fi
+
+if ! command -v codesign >/dev/null 2>&1; then
+  echo "codesign not found. Install Xcode Command Line Tools (xcode-select --install)." >&2
+  exit 1
+fi
+
+if ! command -v xcrun >/dev/null 2>&1; then
+  echo "xcrun not found. Install Xcode Command Line Tools (xcode-select --install)." >&2
+  exit 1
+fi
+
+if ! command -v security >/dev/null 2>&1; then
+  echo "security CLI not found; cannot validate signing identities." >&2
+  exit 1
+fi
+
+if ! security find-identity -v -p codesigning 2>/dev/null | grep -F "$CODESIGN_IDENTITY" >/dev/null 2>&1; then
+  echo "Signing identity not found in keychain: $CODESIGN_IDENTITY" >&2
+  echo "Run 'security find-identity -v -p codesigning' to list available identities." >&2
+  exit 1
+fi
+
+if ! xcrun notarytool history --keychain-profile "$NOTARY_PROFILE" >/dev/null 2>&1; then
+  echo "Notary profile '$NOTARY_PROFILE' is unavailable or invalid." >&2
+  echo "Create/recreate it with: xcrun notarytool store-credentials $NOTARY_PROFILE --apple-id ... --team-id ... --password ..." >&2
+  exit 1
+fi
+
+echo "Trusted packaging prerequisites OK (codesign identity + notary profile)."

package/scripts/validate-usage-alert-rate-e2e.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, chmodSync, rmSync } from 'node:fs'
+import { readTelemetryJsonRow } from './lib/telemetry-row-parser.mjs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const repoRoot = process.cwd()
+const tempDir = mkdtempSync(join(tmpdir(), 'idlewatch-openclaw-alert-rate-'))
+const mockBinPath = join(tempDir, 'openclaw-mock.sh')
+
+function writeMockOpenClaw(binPath) {
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+age_ms="\${MOCK_OPENCLAW_AGE_MS:-500}"
+now_ms=$(node -p 'Date.now()')
+updated_at=$((now_ms - age_ms))
+cat <<JSON
+{"sessions":{"defaults":{"model":"gpt-5.3-codex"},"recent":[{"sessionId":"sess-alert-rate","agentId":"main","model":"gpt-5.3-codex","totalTokens":12345,"updatedAt":\${updated_at},"totalTokensFresh":true}]},"ts":\${now_ms}}
+JSON
+`
+  writeFileSync(binPath, script, 'utf8')
+  chmodSync(binPath, 0o755)
+}
+
+function readRow(output) {
+  return readTelemetryJsonRow(output)
+}
+
+function runSample(ageMs, overrides = {}) {
+  const env = {
+    ...process.env,
+    IDLEWATCH_OPENCLAW_BIN: mockBinPath,
+    IDLEWATCH_USAGE_STALE_MS: '60000',
+    IDLEWATCH_USAGE_STALE_GRACE_MS: '10000',
+    IDLEWATCH_INTERVAL_MS: '1000',
+    MOCK_OPENCLAW_AGE_MS: String(ageMs),
+    ...overrides
+  }
+
+  const out = execFileSync('node', ['bin/idlewatch-agent.js', '--dry-run'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  return readRow(out)
+}
+
+function collectAlertLevels(ageSeries, overrides = {}) {
+  return ageSeries.map((ageMs) => {
+    const row = runSample(ageMs, overrides)
+    return {
+      ageMs,
+      nearMs: row?.source?.usageNearStaleMsThreshold,
+      level: row?.source?.usageAlertLevel,
+      reason: row?.source?.usageAlertReason
+    }
+  })
+}
+
+try {
+  writeMockOpenClaw(mockBinPath)
+
+  const typicalAges = [28000, 33000, 39000, 45000, 50000, 54000]
+  const typical = collectAlertLevels(typicalAges)
+
+  const nonOkTypical = typical.filter((sample) => sample.level !== 'ok')
+  assert.equal(nonOkTypical.length, 0, `expected no non-ok alerts for typical low-traffic ages, got: ${JSON.stringify(nonOkTypical)}`)
+  assert.equal(typical[0].nearMs, 59500, 'expected default near-stale threshold to include stale+grace derivation (59500ms)')
+
+  const deterministicBoundaryAges = [1800, 3600, 5600]
+  const deterministicBoundary = collectAlertLevels(deterministicBoundaryAges, {
+    IDLEWATCH_USAGE_STALE_MS: '3000',
+    IDLEWATCH_USAGE_NEAR_STALE_MS: '1000',
+    IDLEWATCH_USAGE_STALE_GRACE_MS: '1000'
+  })
+
+  assert.equal(deterministicBoundary[0].level, 'notice')
+  assert.equal(deterministicBoundary[0].reason, 'activity-near-stale')
+  assert.equal(deterministicBoundary[1].level, 'warning')
+  assert.equal(deterministicBoundary[1].reason, 'activity-past-threshold')
+  assert.equal(deterministicBoundary[2].level, 'warning')
+  assert.equal(deterministicBoundary[2].reason, 'activity-past-threshold')
+
+  console.log('usage-alert-rate-e2e: ok (typical cadence stays ok; boundary states escalate notice -> warning -> warning)')
+} finally {
+  rmSync(tempDir, { recursive: true, force: true })
+}

package/scripts/validate-usage-freshness-e2e.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, chmodSync, rmSync } from 'node:fs'
+import { readTelemetryJsonRow } from './lib/telemetry-row-parser.mjs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const repoRoot = process.cwd()
+const tempDir = mkdtempSync(join(tmpdir(), 'idlewatch-openclaw-mock-'))
+const mockBinPath = join(tempDir, 'openclaw-mock.sh')
+
+function writeMockOpenClaw(binPath) {
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+age_ms="\${MOCK_OPENCLAW_AGE_MS:-500}"
+now_ms=$(node -p 'Date.now()')
+updated_at=$((now_ms - age_ms))
+cat <<JSON
+{"sessions":{"defaults":{"model":"gpt-5.3-codex"},"recent":[{"sessionId":"sess-e2e","agentId":"main","model":"gpt-5.3-codex","totalTokens":12345,"updatedAt":\${updated_at},"totalTokensFresh":true}]},"ts":\${now_ms}}
+JSON
+`
+  writeFileSync(binPath, script, 'utf8')
+  chmodSync(binPath, 0o755)
+}
+
+function readRow(output) {
+  return readTelemetryJsonRow(output)
+}
+
+function runSample(ageMs) {
+  const env = {
+    ...process.env,
+    IDLEWATCH_OPENCLAW_BIN: mockBinPath,
+    IDLEWATCH_USAGE_STALE_MS: '2000',
+    IDLEWATCH_USAGE_NEAR_STALE_MS: '1000',
+    IDLEWATCH_USAGE_STALE_GRACE_MS: '500',
+    IDLEWATCH_INTERVAL_MS: '1000',
+    MOCK_OPENCLAW_AGE_MS: String(ageMs)
+  }
+
+  const out = execFileSync('node', ['bin/idlewatch-agent.js', '--dry-run'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  return readRow(out)
+}
+
+try {
+  writeMockOpenClaw(mockBinPath)
+
+  const fresh = runSample(500)
+  assert.equal(fresh.source.usageIntegrationStatus, 'ok')
+  assert.equal(fresh.source.usageFreshnessState, 'fresh')
+  assert.equal(fresh.source.usageNearStale, false)
+  assert.equal(fresh.source.usagePastStaleThreshold, false)
+
+  const aging = runSample(1200)
+  assert.equal(aging.source.usageIntegrationStatus, 'ok')
+  assert.equal(aging.source.usageFreshnessState, 'aging')
+  assert.equal(aging.source.usageNearStale, true)
+  assert.equal(aging.source.usagePastStaleThreshold, false)
+
+  const postThresholdGrace = runSample(2200)
+  assert.equal(postThresholdGrace.source.usageIntegrationStatus, 'ok')
+  assert.equal(postThresholdGrace.source.usageFreshnessState, 'aging')
+  assert.equal(postThresholdGrace.source.usagePastStaleThreshold, true)
+
+  const stale = runSample(2600)
+  assert.equal(stale.source.usageIntegrationStatus, 'stale')
+  assert.equal(stale.source.usageFreshnessState, 'stale')
+  assert.equal(stale.source.usageNearStale, true)
+  assert.equal(stale.source.usagePastStaleThreshold, true)
+
+  console.log('usage-freshness-e2e: ok (fresh -> aging -> post-threshold-in-grace -> stale)')
+} finally {
+  rmSync(tempDir, { recursive: true, force: true })
+}

package/skill/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: idlewatch
+description: Collect host CPU/memory/GPU and token telemetry and stream to Firebase Firestore.
+---
+
+# IdleWatch Skill
+
+Install (npm package):
+
+```bash
+npx idlewatch-skill --help
+```
+
+Run collector:
+
+```bash
+idlewatch-agent
+```
+
+Dry-run once (no Firestore write):
+
+```bash
+idlewatch-agent --dry-run
+```
+
+Environment:
+
+- `IDLEWATCH_HOST` optional custom host label
+- `IDLEWATCH_INTERVAL_MS` sampling interval (default 10000)
+- `IDLEWATCH_LOCAL_LOG_PATH` optional local NDJSON durability log path
+- `IDLEWATCH_OPENCLAW_USAGE` usage lookup mode (`auto` or `off`)
+- `FIREBASE_PROJECT_ID`
+- `FIREBASE_SERVICE_ACCOUNT_JSON` (preferred)
+- `FIREBASE_SERVICE_ACCOUNT_B64` (legacy)
+
+Output fields:
+
+- `cpuPct`
+- `memPct`
+- `gpuPct` (darwin best-effort)
+- `tokensPerMin` (OpenClaw usage when available)
+- `openclawModel`
+- `openclawTotalTokens`

package/src/config.js

@@ -0,0 +1,100 @@
+import os from 'os'
+import path from 'path'
+
+/**
+ * Parse and validate a numeric environment variable.
+ * Returns the parsed value or the default.
+ * Throws if the value is set but invalid per the constraint function.
+ */
+function parseNumericEnv(envName, defaultValue, constraint = null) {
+  const raw = process.env[envName]
+  if (raw === undefined || raw === '') return defaultValue
+  const value = Number(raw)
+  if (constraint && !constraint(value)) {
+    throw new Error(`Invalid ${envName}: ${raw}`)
+  }
+  return value
+}
+
+const isPositiveFinite = (v) => Number.isFinite(v) && v > 0
+const isNonNegFinite = (v) => Number.isFinite(v) && v >= 0
+const isNonNegInt = (v) => Number.isInteger(v) && v >= 0
+const isBool01 = (v) => v === 0 || v === 1
+
+/**
+ * Build the full IdleWatch configuration from environment variables.
+ * Throws on invalid values.
+ */
+export function buildConfig() {
+  const HOST = process.env.IDLEWATCH_HOST || os.hostname()
+  const SAFE_HOST = HOST.replace(/[^a-zA-Z0-9_.-]/g, '_')
+
+  const INTERVAL_MS = parseNumericEnv('IDLEWATCH_INTERVAL_MS', 10000, isPositiveFinite)
+  const OPENCLAW_PROBE_TIMEOUT_MS = parseNumericEnv('IDLEWATCH_OPENCLAW_PROBE_TIMEOUT_MS', 2500, isPositiveFinite)
+  const OPENCLAW_PROBE_RETRIES = parseNumericEnv('IDLEWATCH_OPENCLAW_PROBE_RETRIES', 1, isNonNegInt)
+
+  const USAGE_STALE_MS = parseNumericEnv(
+    'IDLEWATCH_USAGE_STALE_MS',
+    Math.max(INTERVAL_MS * 3, 60000),
+    isPositiveFinite
+  )
+
+  const USAGE_STALE_GRACE_MS = parseNumericEnv(
+    'IDLEWATCH_USAGE_STALE_GRACE_MS',
+    Math.min(INTERVAL_MS, 10000),
+    isNonNegFinite
+  )
+
+  const USAGE_NEAR_STALE_MS = parseNumericEnv(
+    'IDLEWATCH_USAGE_NEAR_STALE_MS',
+    Math.floor((USAGE_STALE_MS + USAGE_STALE_GRACE_MS) * 0.85),
+    isNonNegFinite
+  )
+
+  const USAGE_REFRESH_REPROBES = parseNumericEnv('IDLEWATCH_USAGE_REFRESH_REPROBES', 1, isNonNegInt)
+  const USAGE_REFRESH_DELAY_MS = parseNumericEnv('IDLEWATCH_USAGE_REFRESH_DELAY_MS', 250, isNonNegFinite)
+  const USAGE_REFRESH_ON_NEAR_STALE = parseNumericEnv('IDLEWATCH_USAGE_REFRESH_ON_NEAR_STALE', 1, isBool01)
+  const USAGE_IDLE_AFTER_MS = parseNumericEnv('IDLEWATCH_USAGE_IDLE_AFTER_MS', 21600000, isPositiveFinite)
+
+  const OPENCLAW_LAST_GOOD_MAX_AGE_MS = process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS
+    ? parseNumericEnv('IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS', 0, isPositiveFinite)
+    : Math.max(USAGE_STALE_MS + USAGE_STALE_GRACE_MS, 120000)
+
+  const BASE_DIR = path.join(os.homedir(), '.idlewatch')
+
+  const LOCAL_LOG_PATH = process.env.IDLEWATCH_LOCAL_LOG_PATH
+    ? path.resolve(process.env.IDLEWATCH_LOCAL_LOG_PATH)
+    : path.join(BASE_DIR, 'logs', `${SAFE_HOST}-metrics.ndjson`)
+
+  const OPENCLAW_LAST_GOOD_CACHE_PATH = process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH
+    ? path.resolve(process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH)
+    : path.join(BASE_DIR, 'cache', `${SAFE_HOST}-openclaw-last-good.json`)
+
+  return Object.freeze({
+    HOST,
+    SAFE_HOST,
+    INTERVAL_MS,
+    OPENCLAW_USAGE_MODE: (process.env.IDLEWATCH_OPENCLAW_USAGE || 'auto').toLowerCase(),
+    OPENCLAW_BIN_STRICT: process.env.IDLEWATCH_OPENCLAW_BIN_STRICT === '1',
+    OPENCLAW_PROBE_TIMEOUT_MS,
+    OPENCLAW_PROBE_RETRIES,
+    USAGE_STALE_MS,
+    USAGE_STALE_GRACE_MS,
+    USAGE_NEAR_STALE_MS,
+    USAGE_REFRESH_REPROBES,
+    USAGE_REFRESH_DELAY_MS,
+    USAGE_REFRESH_ON_NEAR_STALE,
+    USAGE_IDLE_AFTER_MS,
+    OPENCLAW_LAST_GOOD_MAX_AGE_MS,
+    OPENCLAW_LAST_GOOD_CACHE_PATH,
+    LOCAL_LOG_PATH,
+    REQUIRE_FIREBASE_WRITES: process.env.IDLEWATCH_REQUIRE_FIREBASE_WRITES === '1',
+    FIREBASE: {
+      PROJECT_ID: process.env.FIREBASE_PROJECT_ID,
+      CREDS_FILE: process.env.FIREBASE_SERVICE_ACCOUNT_FILE,
+      CREDS_JSON: process.env.FIREBASE_SERVICE_ACCOUNT_JSON,
+      CREDS_B64: process.env.FIREBASE_SERVICE_ACCOUNT_B64,
+      EMULATOR_HOST: process.env.FIRESTORE_EMULATOR_HOST
+    }
+  })
+}

package/src/enrollment.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline/promises'
+import process from 'node:process'
+import { spawnSync } from 'node:child_process'
+
+function defaultConfigDir() {
+  return path.join(os.homedir(), '.idlewatch')
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true })
+}
+
+function writeSecureFile(filePath, content) {
+  ensureDir(path.dirname(filePath))
+  fs.writeFileSync(filePath, content, { encoding: 'utf8', mode: 0o600 })
+  try {
+    fs.chmodSync(filePath, 0o600)
+  } catch {
+    // best effort on filesystems that ignore chmod
+  }
+}
+
+const MONITOR_TARGET_CHOICES = ['cpu', 'memory', 'gpu', 'openclaw']
+
+function commandExists(bin, args = ['--version']) {
+  const result = spawnSync(bin, args, { stdio: 'ignore' })
+  return result.status === 0
+}
+
+function detectAvailableMonitorTargets() {
+  const available = new Set(['cpu', 'memory'])
+
+  if (process.platform === 'darwin' || commandExists('nvidia-smi', ['--help'])) {
+    available.add('gpu')
+  }
+
+  if (commandExists('openclaw', ['--help'])) {
+    available.add('openclaw')
+  }
+
+  return [...available]
+}
+
+function normalizeMonitorTargets(raw, available) {
+  const fallback = ['cpu', 'memory', ...(available.includes('openclaw') ? ['openclaw'] : []), ...(available.includes('gpu') ? ['gpu'] : [])]
+  if (!raw) return fallback
+
+  const parsed = raw
+    .split(',')
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean)
+    .filter((item) => MONITOR_TARGET_CHOICES.includes(item) && available.includes(item))
+
+  if (parsed.length === 0) return fallback
+  return [...new Set(parsed)]
+}
+
+function tryRustTui({ configDir, outputEnvFile }) {
+  const disabled = process.env.IDLEWATCH_DISABLE_RUST_TUI === '1'
+  if (disabled) return false
+
+  const cargoProbe = spawnSync('cargo', ['--version'], { stdio: 'ignore' })
+  if (cargoProbe.status !== 0) return false
+
+  const manifestPath = path.resolve(process.cwd(), 'tui', 'Cargo.toml')
+  if (!fs.existsSync(manifestPath)) return false
+
+  const run = spawnSync('cargo', ['run', '--quiet', '--manifest-path', manifestPath], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      IDLEWATCH_ENROLL_CONFIG_DIR: configDir,
+      IDLEWATCH_ENROLL_OUTPUT_ENV_FILE: outputEnvFile
+    }
+  })
+
+  if (run.status === 0) {
+    return true
+  }
+
+  return false
+}
+
+function promptModeText() {
+  return `\n╭───────────────────────────────────────────────╮\n│              IdleWatch Setup Wizard           │\n╰───────────────────────────────────────────────╯\n\nChoose setup mode:\n  1) Managed cloud (recommended)\n     Link this device with an API key from idlewatch.com/api\n  2) Local-only (no cloud writes)\n`
+}
+
+export async function runEnrollmentWizard(options = {}) {
+  const nonInteractive = options.nonInteractive || process.env.IDLEWATCH_ENROLL_NON_INTERACTIVE === '1'
+  const configDir = path.resolve(options.configDir || process.env.IDLEWATCH_ENROLL_CONFIG_DIR || defaultConfigDir())
+  const outputEnvFile = path.resolve(options.outputEnvFile || process.env.IDLEWATCH_ENROLL_OUTPUT_ENV_FILE || path.join(configDir, 'idlewatch.env'))
+
+  let mode = options.mode || process.env.IDLEWATCH_ENROLL_MODE || null
+  let cloudApiKey = options.cloudApiKey || process.env.IDLEWATCH_CLOUD_API_KEY || null
+  let cloudIngestUrl = options.cloudIngestUrl || process.env.IDLEWATCH_CLOUD_INGEST_URL || 'https://api.idlewatch.com/api/ingest'
+
+  const availableMonitorTargets = detectAvailableMonitorTargets()
+  let monitorTargets = normalizeMonitorTargets(
+    options.monitorTargets || process.env.IDLEWATCH_MONITOR_TARGETS || '',
+    availableMonitorTargets
+  )
+
+  if (!nonInteractive && tryRustTui({ configDir, outputEnvFile })) {
+    return {
+      mode: 'tui',
+      configDir,
+      outputEnvFile
+    }
+  }
+
+  let rl = null
+  if (!nonInteractive) {
+    rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    console.log(promptModeText())
+    console.log(`Storage path: ${configDir}`)
+    console.log(`Environment file: ${outputEnvFile}`)
+    const modeInput = (await rl.question('\nMode [1/2] (default 1): ')).trim() || '1'
+    mode = modeInput === '2' ? 'local' : 'production'
+  }
+
+  if (!mode) mode = 'production'
+  if (!['production', 'local'].includes(mode)) {
+    throw new Error(`Invalid enrollment mode: ${mode}`)
+  }
+
+  if ((mode === 'production') && !cloudApiKey) {
+    if (!rl) throw new Error('Missing cloud API key (IDLEWATCH_CLOUD_API_KEY).')
+    console.log('\nPaste the API key from idlewatch.com/api.')
+    cloudApiKey = (await rl.question('Cloud API key: ')).trim()
+  }
+
+  if (!nonInteractive && rl) {
+    console.log(`\nDetected monitor targets on this machine: ${availableMonitorTargets.join(', ')}`)
+    const suggested = monitorTargets.join(',')
+    const monitorInput = (await rl.question(`Monitor targets [${suggested}]: `)).trim()
+    monitorTargets = normalizeMonitorTargets(monitorInput || suggested, availableMonitorTargets)
+  }
+
+  const localLogPath = path.join(configDir, 'logs', `${os.hostname().replace(/[^a-zA-Z0-9_.-]/g, '_')}-metrics.ndjson`)
+  const localCachePath = path.join(configDir, 'cache', `${os.hostname().replace(/[^a-zA-Z0-9_.-]/g, '_')}-openclaw-last-good.json`)
+
+  const envLines = [
+    '# Generated by idlewatch-agent quickstart',
+    `IDLEWATCH_MONITOR_TARGETS=${monitorTargets.join(',')}`,
+    `IDLEWATCH_OPENCLAW_USAGE=${monitorTargets.includes('openclaw') ? 'auto' : 'off'}`,
+    `IDLEWATCH_LOCAL_LOG_PATH=${localLogPath}`,
+    `IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH=${localCachePath}`
+  ]
+
+  if (mode === 'local') {
+    envLines.push('# Local-only mode (no cloud/Firebase writes).')
+  }
+
+  if (mode === 'production') {
+    if (!cloudApiKey) {
+      throw new Error('Cloud API key is required for production mode.')
+    }
+    envLines.push(`IDLEWATCH_CLOUD_INGEST_URL=${cloudIngestUrl}`)
+    envLines.push(`IDLEWATCH_CLOUD_API_KEY=${cloudApiKey}`)
+    envLines.push('IDLEWATCH_REQUIRE_CLOUD_WRITES=1')
+  }
+
+  writeSecureFile(outputEnvFile, `${envLines.join('\n')}\n`)
+
+  if (rl) rl.close()
+
+  return {
+    mode,
+    configDir,
+    outputEnvFile,
+    monitorTargets
+  }
+}