idlewatch 0.1.1 → 0.1.3

package/README.md

@@ -1,20 +1,20 @@
-# idlewatch-skill
+# idlewatch
 
 Telemetry collector for IdleWatch.
 
 ## Install / Run
 
 ```bash
-npm install
-npm start
+npm install -g idlewatch
+idlewatch --help
 ```
 
-With npx (after publish):
+Or run it directly with npx:
 
 ```bash
-npx idlewatch-skill --help
-npx idlewatch-skill quickstart
-npx idlewatch-skill --dry-run
+npx idlewatch --help
+npx idlewatch quickstart
+npx idlewatch --dry-run
 ```
 
 `quickstart` runs a first-run setup wizard that writes a local env file and (for production mode) stores a locked-down copy of the service-account key under `~/.idlewatch/`. On hosts with Rust/Cargo available, quickstart launches a ratatui-powered onboarding flow first; otherwise it falls back to the text wizard.
@@ -54,7 +54,7 @@ Use `gpuSource` + `gpuConfidence` in dashboards to decide whether to trust value
 ### Recommended: guided enrollment (external users)
 
 ```bash
-npx idlewatch-skill quickstart
+npx idlewatch quickstart
 ```
 
 The wizard supports:
@@ -62,13 +62,14 @@ The wizard supports:
 - **Emulator mode**: writes `FIREBASE_PROJECT_ID` + `FIRESTORE_EMULATOR_HOST` only.
 - **Local-only mode**: writes no Firebase credentials.
 
-Then load generated env and run:
+Then run a one-shot publish check:
 
 ```bash
-set -a; source "$HOME/.idlewatch/idlewatch.env"; set +a
-idlewatch-agent --once
+idlewatch --once
 ```
 
+The saved config is auto-loaded from `~/.idlewatch/idlewatch.env`, so you should not need to manually source the env file in normal use.
+
 ### Manual wiring
 
 ```bash

package/bin/idlewatch-agent.js

@@ -18,7 +18,7 @@ import { enrichWithOpenClawFleetTelemetry } from '../src/telemetry-mapping.js'
 import pkg from '../package.json' with { type: 'json' }
 
 function printHelp() {
-  console.log(`idlewatch-agent\n\nUsage:\n  idlewatch-agent [quickstart|dashboard] [--dry-run] [--once] [--help]\n\nOptions:\n  quickstart  Run first-run enrollment wizard and generate secure env config\n  dashboard   Launch local dashboard from local IdleWatch logs\n  --dry-run   Collect and print one telemetry sample, then exit without Firebase writes\n  --once      Collect and publish one telemetry sample, then exit\n  --help      Show this help message\n\nEnvironment:\n  IDLEWATCH_HOST                     Optional custom host label (default: hostname)\n  IDLEWATCH_INTERVAL_MS              Sampling interval in ms (default: 10000)\n  IDLEWATCH_LOCAL_LOG_PATH           Optional NDJSON file path for local sample durability\n  IDLEWATCH_DASHBOARD_PORT           Local dashboard HTTP port (default: 4373)\n  IDLEWATCH_OPENCLAW_USAGE           OpenClaw usage lookup mode: auto|off (default: auto)\n  IDLEWATCH_OPENCLAW_PROBE_TIMEOUT_MS OpenClaw command timeout per probe in ms (default: 2500)\n  IDLEWATCH_OPENCLAW_PROBE_RETRIES   Extra OpenClaw probe sweep retries after first pass (default: 1)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES   Max per-command OpenClaw probe output capture in bytes before truncation (default: 2097152 / 2MB)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES_HARD_CAP  Hard cap for auto-retry output capture escalation (default: 16777216 / 16MB)\n  IDLEWATCH_USAGE_STALE_MS           Mark OpenClaw usage stale beyond this age in ms (default: max(interval*3,60000))\n  IDLEWATCH_USAGE_NEAR_STALE_MS      Mark OpenClaw usage as aging beyond this age in ms (default: floor((stale+grace)*0.85))\n  IDLEWATCH_USAGE_STALE_GRACE_MS     Extra grace window before status becomes stale (default: min(interval,10000))\n  IDLEWATCH_USAGE_REFRESH_REPROBES   Forced uncached reprobes when usage crosses stale threshold (default: 1)\n  IDLEWATCH_USAGE_REFRESH_DELAY_MS   Delay between forced stale-threshold reprobes in ms (default: 250)\n  IDLEWATCH_USAGE_REFRESH_ON_NEAR_STALE Trigger refresh when usage is near-stale: 1|0 (default: 1)\n  IDLEWATCH_USAGE_IDLE_AFTER_MS      Downgrade stale usage alerts to idle notice beyond this age in ms (default: 21600000)\n  IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS  Reuse last successful usage snapshot after probe failures up to this age in ms\n  IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH Persist/reuse last successful usage snapshot across restarts (default: ~/.idlewatch/cache/<host>-openclaw-last-good.json)\n  IDLEWATCH_REQUIRE_FIREBASE_WRITES  Require Firebase publish path in --once mode: 1|0 (default: 0)\n  FIREBASE_PROJECT_ID                Firebase project id\n  FIREBASE_SERVICE_ACCOUNT_FILE      Path to service account JSON file (preferred for production)\n  FIREBASE_SERVICE_ACCOUNT_JSON      Raw JSON service account (supported, less secure than file path)\n  FIREBASE_SERVICE_ACCOUNT_B64       Base64-encoded JSON service account (legacy)\n  FIRESTORE_EMULATOR_HOST            Optional Firestore emulator host; allows local writes without service-account creds\n  IDLEWATCH_CLOUD_INGEST_URL         Optional cloud ingest endpoint (e.g. https://idlewatch.com/api/ingest)\n  IDLEWATCH_CLOUD_API_KEY            Cloud API key from dashboard for device linking\n  IDLEWATCH_REQUIRE_CLOUD_WRITES     Require cloud publish path in --once mode: 1|0 (default: 0)\n`)
+  console.log(`idlewatch\n\nUsage:\n  idlewatch [quickstart|configure|dashboard|run] [--dry-run] [--once] [--help]\n\nOptions:\n  quickstart  Run first-run setup TUI and save local IdleWatch config\n  configure   Alias for quickstart; reopen setup to change device name, API key, or metrics\n  dashboard   Launch local dashboard from local IdleWatch logs\n  run         Start the background collector using saved local config\n  --dry-run   Collect and print one telemetry sample, then exit without cloud/Firebase writes\n  --once      Collect and publish one telemetry sample, then exit\n  --help      Show this help message\n\nEnvironment:\n  IDLEWATCH_HOST                     Optional custom host label (default: hostname)\n  IDLEWATCH_INTERVAL_MS              Sampling interval in ms (default: 10000)\n  IDLEWATCH_LOCAL_LOG_PATH           Optional NDJSON file path for local sample durability\n  IDLEWATCH_DASHBOARD_PORT           Local dashboard HTTP port (default: 4373)\n  IDLEWATCH_OPENCLAW_USAGE           OpenClaw usage lookup mode: auto|off (default: auto)\n  IDLEWATCH_OPENCLAW_PROBE_TIMEOUT_MS OpenClaw command timeout per probe in ms (default: 2500)\n  IDLEWATCH_OPENCLAW_PROBE_RETRIES   Extra OpenClaw probe sweep retries after first pass (default: 1)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES   Max per-command OpenClaw probe output capture in bytes before truncation (default: 2097152 / 2MB)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES_HARD_CAP  Hard cap for auto-retry output capture escalation (default: 16777216 / 16MB)\n  IDLEWATCH_USAGE_STALE_MS           Mark OpenClaw usage stale beyond this age in ms (default: max(interval*3,60000))\n  IDLEWATCH_USAGE_NEAR_STALE_MS      Mark OpenClaw usage as aging beyond this age in ms (default: floor((stale+grace)*0.85))\n  IDLEWATCH_USAGE_STALE_GRACE_MS     Extra grace window before status becomes stale (default: min(interval,10000))\n  IDLEWATCH_USAGE_REFRESH_REPROBES   Forced uncached reprobes when usage crosses stale threshold (default: 1)\n  IDLEWATCH_USAGE_REFRESH_DELAY_MS   Delay between forced stale-threshold reprobes in ms (default: 250)\n  IDLEWATCH_USAGE_REFRESH_ON_NEAR_STALE Trigger refresh when usage is near-stale: 1|0 (default: 1)\n  IDLEWATCH_USAGE_IDLE_AFTER_MS      Downgrade stale usage alerts to idle notice beyond this age in ms (default: 21600000)\n  IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS  Reuse last successful usage snapshot after probe failures up to this age in ms\n  IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH Persist/reuse last successful usage snapshot across restarts (default: ~/.idlewatch/cache/<host>-openclaw-last-good.json)\n  IDLEWATCH_REQUIRE_FIREBASE_WRITES  Require Firebase publish path in --once mode: 1|0 (default: 0)\n  FIREBASE_PROJECT_ID                Firebase project id\n  FIREBASE_SERVICE_ACCOUNT_FILE      Path to service account JSON file (preferred for production)\n  FIREBASE_SERVICE_ACCOUNT_JSON      Raw JSON service account (supported, less secure than file path)\n  FIREBASE_SERVICE_ACCOUNT_B64       Base64-encoded JSON service account (legacy)\n  FIRESTORE_EMULATOR_HOST            Optional Firestore emulator host; allows local writes without service-account creds\n  IDLEWATCH_CLOUD_INGEST_URL         Optional cloud ingest endpoint (e.g. https://idlewatch.com/api/ingest)\n  IDLEWATCH_CLOUD_API_KEY            Cloud API key from dashboard for device linking\n  IDLEWATCH_REQUIRE_CLOUD_WRITES     Require cloud publish path in --once mode: 1|0 (default: 0)\n`)
 }
 
 const require = createRequire(import.meta.url)
@@ -38,6 +38,41 @@ function parseEnvFileToObject(envFilePath) {
   return env
 }
 
+function expandSupportedPathVars(value) {
+  if (typeof value !== 'string' || !value) return value
+
+  const home = process.env.HOME || os.homedir()
+  const tmpdir = process.env.TMPDIR || os.tmpdir()
+
+  return value
+    .replace(/^~(?=$|\/)/, home)
+    .replace(/\$\{HOME\}|\$HOME/g, home)
+    .replace(/\$\{TMPDIR\}|\$TMPDIR/g, tmpdir)
+}
+
+function resolveEnvPath(value) {
+  return path.resolve(expandSupportedPathVars(value))
+}
+
+function loadPersistedEnvIntoProcess() {
+  const envFile = path.join(os.homedir(), '.idlewatch', 'idlewatch.env')
+  if (!fs.existsSync(envFile)) return null
+
+  try {
+    const parsed = parseEnvFileToObject(envFile)
+    for (const [key, value] of Object.entries(parsed)) {
+      if (process.env[key]) continue
+      process.env[key] = key.endsWith('_PATH') ? expandSupportedPathVars(value) : value
+    }
+    return { envFile, parsed }
+  } catch (error) {
+    console.error(`Failed to load persisted IdleWatch config from ${envFile}: ${error.message}`)
+    return null
+  }
+}
+
+const persistedEnv = loadPersistedEnvIntoProcess()
+
 function parseMonitorTargets(raw) {
   const allowed = new Set(['cpu', 'memory', 'gpu', 'openclaw'])
   const fallback = ['cpu', 'memory', 'openclaw', 'gpu']
@@ -70,7 +105,7 @@ function formatBytes(bytes) {
 
 function resolveDashboardLogPath(host) {
   if (process.env.IDLEWATCH_LOCAL_LOG_PATH) {
-    return path.resolve(process.env.IDLEWATCH_LOCAL_LOG_PATH)
+    return resolveEnvPath(process.env.IDLEWATCH_LOCAL_LOG_PATH)
   }
 
   const envFile = path.join(os.homedir(), '.idlewatch', 'idlewatch.env')
@@ -78,7 +113,7 @@ function resolveDashboardLogPath(host) {
     try {
       const parsed = parseEnvFileToObject(envFile)
       if (parsed.IDLEWATCH_LOCAL_LOG_PATH) {
-        return path.resolve(parsed.IDLEWATCH_LOCAL_LOG_PATH)
+        return resolveEnvPath(parsed.IDLEWATCH_LOCAL_LOG_PATH)
       }
     } catch {
       // ignore malformed env file and fallback
@@ -319,9 +354,11 @@ function runLocalDashboard({ host }) {
 }
 
 const argv = process.argv.slice(2)
-const quickstartRequested = argv[0] === 'quickstart' || argv.includes('--quickstart')
-const dashboardRequested = argv[0] === 'dashboard' || argv.includes('--dashboard')
 const args = new Set(argv)
+const dashboardRequested = argv[0] === 'dashboard' || argv.includes('--dashboard')
+const runRequested = argv[0] === 'run' || argv.includes('--run')
+const interactiveDefaultRequested = argv.length === 0 && process.stdin.isTTY && process.stdout.isTTY
+const quickstartRequested = argv[0] === 'quickstart' || argv[0] === 'configure' || argv.includes('--quickstart') || argv.includes('--configure') || (interactiveDefaultRequested && !dashboardRequested && !runRequested)
 if (args.has('--help') || args.has('-h')) {
   printHelp()
   process.exit(0)
@@ -336,7 +373,6 @@ if (dashboardRequested) {
 if (quickstartRequested) {
   try {
     const result = await runEnrollmentWizard()
-    console.log(`Enrollment complete. Mode=${result.mode} envFile=${result.outputEnvFile}`)
 
     const enrolledEnv = parseEnvFileToObject(result.outputEnvFile)
     const onceRun = spawnSync(process.execPath, [process.argv[1], '--once'], {
@@ -348,12 +384,15 @@ if (quickstartRequested) {
     })
 
     if (onceRun.status === 0) {
-      console.log('✅ Initial telemetry sample sent successfully.')
+      console.log(`✅ Setup complete. Mode=${result.mode} device=${result.deviceName} envFile=${result.outputEnvFile}`)
+      console.log('Initial telemetry sample sent successfully.')
       process.exit(0)
     }
 
-    console.log('⚠️ Initial --once sample did not complete successfully.')
-    console.log(`You can retry with: set -a; source "${result.outputEnvFile}"; set +a && idlewatch-agent --once`)
+    console.error(`⚠️ Setup is not finished yet. Mode=${result.mode} device=${result.deviceName} envFile=${result.outputEnvFile}`)
+    console.error('The first required telemetry sample did not publish successfully, so this device may not be linked yet.')
+    console.error(`Retry with: set -a; source "${result.outputEnvFile}"; set +a && idlewatch --once`)
+    console.error('Or rerun: idlewatch quickstart')
     process.exit(onceRun.status ?? 1)
   } catch (err) {
     console.error(`Enrollment failed: ${err.message}`)
@@ -363,8 +402,14 @@ if (quickstartRequested) {
 
 const DRY_RUN = args.has('--dry-run')
 const ONCE = args.has('--once')
+const DEVICE_NAME = (process.env.IDLEWATCH_DEVICE_NAME || process.env.IDLEWATCH_HOST || os.hostname()).trim()
+const DEVICE_ID = (process.env.IDLEWATCH_DEVICE_ID || DEVICE_NAME)
+  .trim()
+  .toLowerCase()
+  .replace(/[^a-z0-9_.-]+/g, '-')
+  .replace(/^-+|-+$/g, '') || 'device'
 const HOST = process.env.IDLEWATCH_HOST || os.hostname()
-const SAFE_HOST = HOST.replace(/[^a-zA-Z0-9_.-]/g, '_')
+const SAFE_HOST = DEVICE_ID.replace(/[^a-zA-Z0-9_.-]/g, '_')
 const INTERVAL_MS = Number(process.env.IDLEWATCH_INTERVAL_MS || 10000)
 const PROJECT_ID = process.env.FIREBASE_PROJECT_ID
 const CREDS_FILE = process.env.FIREBASE_SERVICE_ACCOUNT_FILE
@@ -379,8 +424,8 @@ const MONITOR_GPU = MONITOR_TARGETS.has('gpu')
 const MONITOR_OPENCLAW = MONITOR_TARGETS.has('openclaw')
 const EFFECTIVE_OPENCLAW_MODE = MONITOR_OPENCLAW ? OPENCLAW_USAGE_MODE : 'off'
 const REQUIRE_FIREBASE_WRITES = process.env.IDLEWATCH_REQUIRE_FIREBASE_WRITES === '1'
-const CLOUD_INGEST_URL = process.env.IDLEWATCH_CLOUD_INGEST_URL
-const CLOUD_API_KEY = process.env.IDLEWATCH_CLOUD_API_KEY
+const CLOUD_INGEST_URL = (process.env.IDLEWATCH_CLOUD_INGEST_URL || '').trim()
+const CLOUD_API_KEY = (process.env.IDLEWATCH_CLOUD_API_KEY || '').trim().replace(/^['"]|['"]$/g, '')
 const REQUIRE_CLOUD_WRITES = process.env.IDLEWATCH_REQUIRE_CLOUD_WRITES === '1'
 let cloudIngestKickedOut = false
 let cloudIngestKickoutReason = null
@@ -399,7 +444,7 @@ const OPENCLAW_PROBE_RETRIES = process.env.IDLEWATCH_OPENCLAW_PROBE_RETRIES
 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)
+  ? resolveEnvPath(process.env.IDLEWATCH_LOCAL_LOG_PATH)
   : path.join(BASE_DIR, 'logs', `${SAFE_HOST}-metrics.ndjson`)
 
 if (!Number.isFinite(INTERVAL_MS) || INTERVAL_MS <= 0) {
@@ -522,7 +567,7 @@ if (process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS && (!Number.isFinite(OPE
 }
 
 const OPENCLAW_LAST_GOOD_CACHE_PATH = process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH
-  ? path.resolve(process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH)
+  ? resolveEnvPath(process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH)
   : path.join(BASE_DIR, 'cache', `${SAFE_HOST}-openclaw-last-good.json`)
 
 let appReady = false
@@ -579,9 +624,9 @@ if (firebaseConfigError) {
   process.exit(1)
 }
 
-if (!appReady) {
+if (!appReady && !(CLOUD_INGEST_URL && CLOUD_API_KEY)) {
   console.error(
-    'Firebase is not configured. Running in local-only mode (stdout logging only). Set FIREBASE_PROJECT_ID + FIREBASE_SERVICE_ACCOUNT_FILE (preferred, or FIREBASE_SERVICE_ACCOUNT_JSON / FIREBASE_SERVICE_ACCOUNT_B64), or use FIREBASE_PROJECT_ID + FIRESTORE_EMULATOR_HOST for emulator writes.'
+    'Firebase is not configured. Running without Firebase writes. Set FIREBASE_PROJECT_ID + FIREBASE_SERVICE_ACCOUNT_FILE (preferred, or FIREBASE_SERVICE_ACCOUNT_JSON / FIREBASE_SERVICE_ACCOUNT_B64), use FIREBASE_PROJECT_ID + FIRESTORE_EMULATOR_HOST for emulator writes, or configure cloud ingest via idlewatch setup.'
   )
 }
 
@@ -1276,6 +1321,10 @@ async function collectSample() {
 
   const row = {
     host: HOST,
+    hostId: HOST,
+    hostName: HOST,
+    deviceId: DEVICE_ID,
+    deviceName: DEVICE_NAME,
     ts: sampleAtMs,
     cpuPct: MONITOR_CPU ? cpuPct() : null,
     memPct: MONITOR_MEMORY ? usedMemPct : null,
@@ -1360,10 +1409,10 @@ async function gracefulShutdown(signal) {
   if (stopped) return
   stopped = true
   if (inflightTick) {
-    console.log(`idlewatch-agent received ${signal}, waiting for in-flight sample…`)
+    console.log(`idlewatch received ${signal}, waiting for in-flight sample…`)
     try { await inflightTick } catch { /* already logged */ }
   }
-  console.log('idlewatch-agent stopped')
+  console.log('idlewatch stopped')
   process.exit(0)
 }
 
@@ -1373,7 +1422,7 @@ process.on('SIGTERM', () => gracefulShutdown('SIGTERM'))
 if (DRY_RUN || ONCE) {
   const mode = DRY_RUN ? 'dry-run' : 'once'
   console.log(
-    `idlewatch-agent ${mode} host=${HOST} intervalMs=${INTERVAL_MS} firebase=${appReady} localLog=${LOCAL_LOG_PATH}`
+    `idlewatch ${mode} host=${HOST} device=${DEVICE_NAME} deviceId=${DEVICE_ID} intervalMs=${INTERVAL_MS} firebase=${appReady} localLog=${LOCAL_LOG_PATH} env=${persistedEnv?.envFile || 'process'}`
   )
   tick()
     .then(() => process.exit(0))
@@ -1383,7 +1432,7 @@ if (DRY_RUN || ONCE) {
     })
 } else {
   console.log(
-    `idlewatch-agent started host=${HOST} intervalMs=${INTERVAL_MS} firebase=${appReady} localLog=${LOCAL_LOG_PATH} monitorTargets=${[...MONITOR_TARGETS].join(',')} openclawUsage=${EFFECTIVE_OPENCLAW_MODE}`
+    `idlewatch started host=${HOST} device=${DEVICE_NAME} deviceId=${DEVICE_ID} intervalMs=${INTERVAL_MS} firebase=${appReady} localLog=${LOCAL_LOG_PATH} monitorTargets=${[...MONITOR_TARGETS].join(',')} openclawUsage=${EFFECTIVE_OPENCLAW_MODE} env=${persistedEnv?.envFile || 'process'}`
   )
   loop()
 }

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "idlewatch",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Host telemetry collector for IdleWatch",
   "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "skill",
+    "tui/src",
+    "tui/Cargo.toml",
+    "tui/Cargo.lock",
+    "README.md",
+    ".env.example"
+  ],
   "bin": {
     "idlewatch": "bin/idlewatch-agent.js",
     "idlewatch-agent": "bin/idlewatch-agent.js",

package/scripts/install-macos-launch-agent.sh

@@ -43,6 +43,7 @@ cat > "$PLIST_PATH" <<'PLIST'
   <key>ProgramArguments</key>
   <array>
     <string>{{BIN_PATH}}</string>
+    <string>--run</string>
   </array>
   <key>RunAtLoad</key>
   <true/>

package/scripts/validate-onboarding.mjs

@@ -1,42 +1,80 @@
 import fs from 'node:fs'
+import http from 'node:http'
 import os from 'node:os'
 import path from 'node:path'
-import { spawnSync } from 'node:child_process'
+import { spawn } from 'node:child_process'
 
 const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..')
 const binPath = path.join(repoRoot, 'bin', 'idlewatch-agent.js')
 const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'idlewatch-onboarding-'))
 
-try {
-  const sourceCreds = path.join(tmpRoot, 'service-account.json')
-  fs.writeFileSync(
-    sourceCreds,
-    JSON.stringify({
-      type: 'service_account',
-      project_id: 'idlewatch-test-project',
-      private_key_id: 'abc123',
-      private_key: '-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----\n',
-      client_email: 'idlewatch@idlewatch-test-project.iam.gserviceaccount.com',
-      client_id: '123'
+const requests = []
+const server = http.createServer((req, res) => {
+  let body = ''
+  req.on('data', (chunk) => {
+    body += chunk
+  })
+  req.on('end', () => {
+    requests.push({
+      method: req.method,
+      url: req.url,
+      headers: req.headers,
+      body
     })
-  )
+    res.writeHead(200, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ ok: true }))
+  })
+})
+
+await new Promise((resolve, reject) => {
+  server.listen(0, '127.0.0.1', () => resolve())
+  server.once('error', reject)
+})
+
+const address = server.address()
+const cloudIngestUrl = `http://127.0.0.1:${address.port}/api/ingest`
 
+function runQuickstart(env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [binPath, 'quickstart'], {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk
+    })
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code, stdout, stderr }))
+  })
+}
+
+try {
   const envOut = path.join(tmpRoot, 'generated.env')
   const configDir = path.join(tmpRoot, 'config')
-  const run = spawnSync(process.execPath, [binPath, 'quickstart'], {
-    env: {
-      ...process.env,
-      IDLEWATCH_ENROLL_NON_INTERACTIVE: '1',
-      IDLEWATCH_ENROLL_MODE: 'production',
-      IDLEWATCH_ENROLL_PROJECT_ID: 'idlewatch-test-project',
-      IDLEWATCH_ENROLL_SERVICE_ACCOUNT_FILE: sourceCreds,
-      IDLEWATCH_ENROLL_OUTPUT_ENV_FILE: envOut,
-      IDLEWATCH_ENROLL_CONFIG_DIR: configDir
-    },
-    encoding: 'utf8'
+  const localLogPath = path.join(configDir, 'logs', 'validator-box-metrics.ndjson')
+  const lastGoodCachePath = path.join(configDir, 'cache', 'validator-box-openclaw-last-good.json')
+
+  const run = await runQuickstart({
+    ...process.env,
+    IDLEWATCH_ENROLL_NON_INTERACTIVE: '1',
+    IDLEWATCH_ENROLL_MODE: 'production',
+    IDLEWATCH_CLOUD_API_KEY: 'iwk_abcdefghijklmnopqrstuvwxyz123456',
+    IDLEWATCH_CLOUD_INGEST_URL: cloudIngestUrl,
+    IDLEWATCH_ENROLL_OUTPUT_ENV_FILE: envOut,
+    IDLEWATCH_ENROLL_CONFIG_DIR: configDir,
+    IDLEWATCH_DEVICE_NAME: 'Validator Box',
+    IDLEWATCH_DEVICE_ID: 'validator-box',
+    IDLEWATCH_MONITOR_TARGETS: 'cpu,memory',
+    IDLEWATCH_OPENCLAW_USAGE: 'off'
   })
 
-  if (run.status !== 0) {
+  if (run.code !== 0) {
     throw new Error(`quickstart failed\nstdout:\n${run.stdout}\nstderr:\n${run.stderr}`)
   }
 
@@ -45,19 +83,37 @@ try {
   }
 
   const envContent = fs.readFileSync(envOut, 'utf8')
-  if (!envContent.includes('FIREBASE_PROJECT_ID=idlewatch-test-project')) {
-    throw new Error('env file missing FIREBASE_PROJECT_ID')
+  for (const requiredLine of [
+    'IDLEWATCH_DEVICE_NAME=Validator Box',
+    'IDLEWATCH_DEVICE_ID=validator-box',
+    'IDLEWATCH_MONITOR_TARGETS=cpu,memory',
+    'IDLEWATCH_OPENCLAW_USAGE=off',
+    `IDLEWATCH_LOCAL_LOG_PATH=${localLogPath}`,
+    `IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH=${lastGoodCachePath}`,
+    `IDLEWATCH_CLOUD_INGEST_URL=${cloudIngestUrl}`,
+    'IDLEWATCH_CLOUD_API_KEY=iwk_abcdefghijklmnopqrstuvwxyz123456',
+    'IDLEWATCH_REQUIRE_CLOUD_WRITES=1'
+  ]) {
+    if (!envContent.includes(requiredLine)) {
+      throw new Error(`env file missing ${requiredLine}`)
+    }
+  }
+
+  if (!run.stdout.includes('✅ Setup complete.')) {
+    throw new Error('quickstart success output did not include setup completion summary')
   }
-  if (!envContent.includes('FIREBASE_SERVICE_ACCOUNT_FILE=')) {
-    throw new Error('env file missing FIREBASE_SERVICE_ACCOUNT_FILE')
+
+  if (requests.length === 0) {
+    throw new Error('quickstart did not send the initial telemetry sample')
   }
 
-  const copiedCreds = path.join(configDir, 'credentials', 'idlewatch-test-project-service-account.json')
-  if (!fs.existsSync(copiedCreds)) {
-    throw new Error('quickstart did not copy service account file to secure credentials path')
+  const telemetry = JSON.parse(requests[0].body)
+  if (telemetry.deviceId !== 'validator-box') {
+    throw new Error('initial telemetry sample used unexpected device id')
   }
 
   console.log('onboarding validation passed')
 } finally {
+  await new Promise((resolve) => server.close(resolve))
   fs.rmSync(tmpRoot, { recursive: true, force: true })
 }

package/src/config.js

@@ -21,6 +21,22 @@ const isNonNegFinite = (v) => Number.isFinite(v) && v >= 0
 const isNonNegInt = (v) => Number.isInteger(v) && v >= 0
 const isBool01 = (v) => v === 0 || v === 1
 
+function expandSupportedPathVars(value) {
+  if (typeof value !== 'string' || !value) return value
+
+  const home = process.env.HOME || os.homedir()
+  const tmpdir = process.env.TMPDIR || os.tmpdir()
+
+  return value
+    .replace(/^~(?=$|\/)/, home)
+    .replace(/\$\{HOME\}|\$HOME/g, home)
+    .replace(/\$\{TMPDIR\}|\$TMPDIR/g, tmpdir)
+}
+
+function resolveEnvPath(value) {
+  return path.resolve(expandSupportedPathVars(value))
+}
+
 /**
  * Build the full IdleWatch configuration from environment variables.
  * Throws on invalid values.
@@ -63,11 +79,11 @@ export function buildConfig() {
   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)
+    ? resolveEnvPath(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)
+    ? resolveEnvPath(process.env.IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH)
     : path.join(BASE_DIR, 'cache', `${SAFE_HOST}-openclaw-last-good.json`)
 
   return Object.freeze({

package/src/enrollment.js

@@ -3,6 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import readline from 'node:readline/promises'
 import process from 'node:process'
+import { fileURLToPath } from 'node:url'
 import { spawnSync } from 'node:child_process'
 
 function defaultConfigDir() {
@@ -24,6 +25,8 @@ function writeSecureFile(filePath, content) {
 }
 
 const MONITOR_TARGET_CHOICES = ['cpu', 'memory', 'gpu', 'openclaw']
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = path.resolve(MODULE_DIR, '..')
 
 function commandExists(bin, args = ['--version']) {
   const result = spawnSync(bin, args, { stdio: 'ignore' })
@@ -58,15 +61,48 @@ function normalizeMonitorTargets(raw, available) {
   return [...new Set(parsed)]
 }
 
+function normalizeCloudApiKey(raw) {
+  const trimmed = String(raw || '').trim()
+  if (!trimmed) return ''
+
+  const token = trimmed
+    .split(/\s+/)
+    .find((part) => part.startsWith('iwk_'))
+
+  if (token) {
+    return token.replace(/^['"]|['",]$/g, '')
+  }
+
+  return trimmed.replace(/^['"]|['"]$/g, '')
+}
+
+function looksLikeCloudApiKey(value) {
+  return /^iwk_[A-Za-z0-9_-]{20,}$/.test(String(value || '').trim())
+}
+
+function normalizeDeviceName(raw, fallback = os.hostname()) {
+  const value = String(raw || '').trim().replace(/\s+/g, ' ')
+  return value || fallback
+}
+
+function sanitizeDeviceId(raw, fallback = os.hostname()) {
+  const base = normalizeDeviceName(raw, fallback).toLowerCase()
+  const sanitized = base
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+  return sanitized || normalizeDeviceName(fallback).replace(/[^a-zA-Z0-9_.-]/g, '_')
+}
+
 function tryRustTui({ configDir, outputEnvFile }) {
   const disabled = process.env.IDLEWATCH_DISABLE_RUST_TUI === '1'
-  if (disabled) return false
+  if (disabled) return { ok: false, reason: 'disabled' }
 
   const cargoProbe = spawnSync('cargo', ['--version'], { stdio: 'ignore' })
-  if (cargoProbe.status !== 0) return false
+  if (cargoProbe.status !== 0) return { ok: false, reason: 'cargo-missing' }
 
-  const manifestPath = path.resolve(process.cwd(), 'tui', 'Cargo.toml')
-  if (!fs.existsSync(manifestPath)) return false
+  const manifestPath = path.join(PACKAGE_ROOT, 'tui', 'Cargo.toml')
+  if (!fs.existsSync(manifestPath)) return { ok: false, reason: 'manifest-missing', manifestPath }
 
   const run = spawnSync('cargo', ['run', '--quiet', '--manifest-path', manifestPath], {
     stdio: 'inherit',
@@ -78,10 +114,10 @@ function tryRustTui({ configDir, outputEnvFile }) {
   })
 
   if (run.status === 0) {
-    return true
+    return { ok: true, manifestPath }
   }
 
-  return false
+  return { ok: false, reason: `cargo-run-failed:${run.status ?? 'unknown'}`, manifestPath }
 }
 
 function promptModeText() {
@@ -94,8 +130,9 @@ export async function runEnrollmentWizard(options = {}) {
   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 cloudApiKey = normalizeCloudApiKey(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'
+  let deviceName = normalizeDeviceName(options.deviceName || process.env.IDLEWATCH_DEVICE_NAME || os.hostname())
 
   const availableMonitorTargets = detectAvailableMonitorTargets()
   let monitorTargets = normalizeMonitorTargets(
@@ -103,11 +140,18 @@ export async function runEnrollmentWizard(options = {}) {
     availableMonitorTargets
   )
 
-  if (!nonInteractive && tryRustTui({ configDir, outputEnvFile })) {
-    return {
-      mode: 'tui',
-      configDir,
-      outputEnvFile
+  if (!nonInteractive) {
+    const tuiResult = tryRustTui({ configDir, outputEnvFile })
+    if (tuiResult.ok) {
+      return {
+        mode: 'tui',
+        configDir,
+        outputEnvFile
+      }
+    }
+
+    if (!['disabled', 'cargo-missing'].includes(tuiResult.reason || '')) {
+      console.warn(`IdleWatch TUI unavailable (${tuiResult.reason || 'unknown'}). Falling back to text setup.`)
     }
   }
 
@@ -119,6 +163,8 @@ export async function runEnrollmentWizard(options = {}) {
     console.log(`Environment file: ${outputEnvFile}`)
     const modeInput = (await rl.question('\nMode [1/2] (default 1): ')).trim() || '1'
     mode = modeInput === '2' ? 'local' : 'production'
+    const deviceNameInput = (await rl.question(`Device name [${deviceName}]: `)).trim()
+    deviceName = normalizeDeviceName(deviceNameInput || deviceName)
   }
 
   if (!mode) mode = 'production'
@@ -129,7 +175,7 @@ export async function runEnrollmentWizard(options = {}) {
   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()
+    cloudApiKey = normalizeCloudApiKey(await rl.question('Cloud API key: '))
   }
 
   if (!nonInteractive && rl) {
@@ -139,11 +185,14 @@ export async function runEnrollmentWizard(options = {}) {
     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 safeDeviceId = sanitizeDeviceId(options.deviceId || process.env.IDLEWATCH_DEVICE_ID || deviceName, os.hostname())
+  const localLogPath = path.join(configDir, 'logs', `${safeDeviceId}-metrics.ndjson`)
+  const localCachePath = path.join(configDir, 'cache', `${safeDeviceId}-openclaw-last-good.json`)
 
   const envLines = [
     '# Generated by idlewatch-agent quickstart',
+    `IDLEWATCH_DEVICE_NAME=${deviceName}`,
+    `IDLEWATCH_DEVICE_ID=${safeDeviceId}`,
     `IDLEWATCH_MONITOR_TARGETS=${monitorTargets.join(',')}`,
     `IDLEWATCH_OPENCLAW_USAGE=${monitorTargets.includes('openclaw') ? 'auto' : 'off'}`,
     `IDLEWATCH_LOCAL_LOG_PATH=${localLogPath}`,
@@ -155,8 +204,8 @@ export async function runEnrollmentWizard(options = {}) {
   }
 
   if (mode === 'production') {
-    if (!cloudApiKey) {
-      throw new Error('Cloud API key is required for production mode.')
+    if (!cloudApiKey || !looksLikeCloudApiKey(cloudApiKey)) {
+      throw new Error('Cloud API key is invalid. Copy the full key from idlewatch.com/api (starts with iwk_).')
     }
     envLines.push(`IDLEWATCH_CLOUD_INGEST_URL=${cloudIngestUrl}`)
     envLines.push(`IDLEWATCH_CLOUD_API_KEY=${cloudApiKey}`)
@@ -171,6 +220,8 @@ export async function runEnrollmentWizard(options = {}) {
     mode,
     configDir,
     outputEnvFile,
-    monitorTargets
+    monitorTargets,
+    deviceName,
+    deviceId: safeDeviceId
   }
 }