idlewatch 0.1.0

package/scripts/validate-dry-run-schema.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { extractJsonCandidates } from './lib/telemetry-row-parser.mjs'
+
+const command = process.argv[2] || 'node'
+const args = process.argv.slice(3)
+
+const TIMEOUT_MS_RAW = process.env.IDLEWATCH_DRY_RUN_TIMEOUT_MS
+const DRY_RUN_TIMEOUT_MS = TIMEOUT_MS_RAW
+  ? Number(TIMEOUT_MS_RAW)
+  : 15000
+
+if (!Number.isFinite(DRY_RUN_TIMEOUT_MS) || DRY_RUN_TIMEOUT_MS <= 0) {
+  console.error('IDLEWATCH_DRY_RUN_TIMEOUT_MS must be a finite positive number when set')
+  process.exit(1)
+}
+
+function collectOutput(stderrBuffer, stdoutBuffer) {
+  const parts = [stdoutBuffer, stderrBuffer].filter(Boolean)
+  const output = parts.join('')
+  return String(output || '')
+}
+
+function run() {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: DRY_RUN_TIMEOUT_MS,
+    maxBuffer: 8 * 1024 * 1024,
+    killSignal: 'SIGINT'
+  })
+
+  const out = collectOutput(result.stdout, result.stderr)
+  const timedOut = result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGINT'
+  const maybeCandidates = extractJsonCandidates(out)
+
+  if (timedOut) {
+    console.error(`dry-run timed out after ${DRY_RUN_TIMEOUT_MS}ms; attempting to validate captured output from partial row`)
+  } else if (result.error) {
+    if (!out.trim()) {
+      throw result.error
+    }
+    console.error(`dry-run process error: ${result.error.message}; validating captured output anyway`)
+  } else if (result.status !== 0 && !out.trim()) {
+    throw new Error(`dry-run exited with non-zero status ${result.status}`)
+  } else if (result.status !== 0) {
+    console.error(`dry-run exited with non-zero status ${result.status}; validating captured output anyway`)
+  }
+
+  for (let i = maybeCandidates.length - 1; i >= 0; i -= 1) {
+    const candidate = maybeCandidates[i]
+    try {
+      const row = JSON.parse(candidate)
+      validateRow(row)
+      console.log(`dry-run schema ok (${command} ${args.join(' ')})`)
+      return
+    } catch {
+      // ignore and continue with the next JSON candidate
+    }
+  }
+
+  throw new Error('No telemetry JSON row found in dry-run output')
+}
+
+
+function assertNumberOrNull(value, field) {
+  assert.ok(value === null || Number.isFinite(value), `${field} must be a finite number or null`)
+}
+
+const REQUIRE_OPENCLAW_USAGE = process.env.IDLEWATCH_REQUIRE_OPENCLAW_USAGE === '1'
+const MAX_OPENCLAW_USAGE_AGE_MS_RAW = process.env.IDLEWATCH_MAX_OPENCLAW_USAGE_AGE_MS
+const MAX_OPENCLAW_USAGE_AGE_MS = MAX_OPENCLAW_USAGE_AGE_MS_RAW
+  ? Number(MAX_OPENCLAW_USAGE_AGE_MS_RAW)
+  : null
+
+if (MAX_OPENCLAW_USAGE_AGE_MS_RAW) {
+  assert.ok(Number.isFinite(MAX_OPENCLAW_USAGE_AGE_MS) && MAX_OPENCLAW_USAGE_AGE_MS > 0, 'IDLEWATCH_MAX_OPENCLAW_USAGE_AGE_MS must be a number > 0 when set')
+}
+
+function validateRow(row) {
+  assert.equal(typeof row.host, 'string', 'host must be a string')
+  assert.ok(Number.isFinite(row.ts), 'ts must be a finite number')
+
+  assertNumberOrNull(row.cpuPct, 'cpuPct')
+  assertNumberOrNull(row.memPct, 'memPct')
+  assertNumberOrNull(row.memUsedPct, 'memUsedPct')
+  assertNumberOrNull(row.memPressurePct, 'memPressurePct')
+  assert.ok(['normal', 'warning', 'critical', 'unavailable'].includes(row.memPressureClass), 'memPressureClass invalid')
+
+  assertNumberOrNull(row.gpuPct, 'gpuPct')
+  assert.equal(typeof row.gpuSource, 'string', 'gpuSource must be string')
+  assert.ok(['high', 'medium', 'low', 'none'].includes(row.gpuConfidence), 'gpuConfidence invalid')
+  assertNumberOrNull(row.gpuSampleWindowMs, 'gpuSampleWindowMs')
+
+  assertNumberOrNull(row.tokensPerMin, 'tokensPerMin')
+  assert.ok(row.openclawModel === null || typeof row.openclawModel === 'string', 'openclawModel must be string or null')
+  assertNumberOrNull(row.openclawTotalTokens, 'openclawTotalTokens')
+  assert.ok(row.openclawSessionId === null || typeof row.openclawSessionId === 'string', 'openclawSessionId must be string or null')
+  assert.ok(row.openclawAgentId === null || typeof row.openclawAgentId === 'string', 'openclawAgentId must be string or null')
+  assertNumberOrNull(row.openclawUsageTs, 'openclawUsageTs')
+  assertNumberOrNull(row.openclawUsageAgeMs, 'openclawUsageAgeMs')
+
+  assert.equal(typeof row.source, 'object', 'source must exist')
+  const source = row.source
+
+  assert.equal(typeof row.schemaFamily, 'string', 'schemaFamily must be string')
+  assert.equal(typeof row.schemaVersion, 'string', 'schemaVersion must be string')
+  assert.ok(Array.isArray(row.schemaCompat), 'schemaCompat must be array')
+  assert.equal(typeof row.fleet, 'object', 'fleet must exist')
+  assert.equal(typeof row.fleet.host, 'string', 'fleet.host must be string')
+  assert.ok(Number.isFinite(row.fleet.collectedAtMs), 'fleet.collectedAtMs must be number')
+  assert.equal(typeof row.fleet.resources, 'object', 'fleet.resources must exist')
+  assertNumberOrNull(row.fleet.resources.cpuPct, 'fleet.resources.cpuPct')
+  assertNumberOrNull(row.fleet.resources.memUsedPct, 'fleet.resources.memUsedPct')
+  assertNumberOrNull(row.fleet.resources.memPressurePct, 'fleet.resources.memPressurePct')
+  assert.ok(['normal', 'warning', 'critical', 'unavailable'].includes(row.fleet.resources.memPressureClass), 'fleet.resources.memPressureClass invalid')
+  assert.equal(typeof row.fleet.usage, 'object', 'fleet.usage must exist')
+  assert.ok(row.fleet.usage.model === null || typeof row.fleet.usage.model === 'string', 'fleet.usage.model invalid')
+  assertNumberOrNull(row.fleet.usage.totalTokens, 'fleet.usage.totalTokens')
+  assertNumberOrNull(row.fleet.usage.tokensPerMin, 'fleet.usage.tokensPerMin')
+  assert.ok(row.fleet.usage.sessionId === null || typeof row.fleet.usage.sessionId === 'string', 'fleet.usage.sessionId invalid')
+  assert.ok(row.fleet.usage.agentId === null || typeof row.fleet.usage.agentId === 'string', 'fleet.usage.agentId invalid')
+  assertNumberOrNull(row.fleet.usage.usageTimestampMs, 'fleet.usage.usageTimestampMs')
+  assertNumberOrNull(row.fleet.usage.usageAgeMs, 'fleet.usage.usageAgeMs')
+  assert.ok(row.fleet.usage.freshnessState === null || ['fresh', 'aging', 'stale', 'unknown', 'disabled'].includes(row.fleet.usage.freshnessState), 'fleet.usage.freshnessState invalid')
+  assert.ok(['ok', 'stale', 'disabled', 'unavailable'].includes(row.fleet.usage.integrationStatus), 'fleet.usage.integrationStatus invalid')
+  assert.ok(['ok', 'disabled', 'unavailable'].includes(row.fleet.usage.ingestionStatus), 'fleet.usage.ingestionStatus invalid')
+  assert.ok(['fresh', 'aging', 'stale', 'unknown', 'disabled', 'unavailable'].includes(row.fleet.usage.activityStatus), 'fleet.usage.activityStatus invalid')
+  assert.ok(['ok', 'notice', 'warning', 'critical', 'off'].includes(row.fleet.usage.alertLevel), 'fleet.usage.alertLevel invalid')
+  assert.equal(typeof row.fleet.provenance, 'object', 'fleet.provenance must exist')
+  assert.equal(typeof row.fleet.provenance.collector, 'string', 'fleet.provenance.collector must be string')
+  assert.ok(row.fleet.provenance.collectorVersion === null || typeof row.fleet.provenance.collectorVersion === 'string', 'fleet.provenance.collectorVersion invalid')
+  assert.ok(['openclaw', 'disabled', 'unavailable'].includes(source.usage), 'source.usage invalid')
+  assert.ok(['ok', 'stale', 'disabled', 'unavailable'].includes(source.usageIntegrationStatus), 'source.usageIntegrationStatus invalid')
+  assert.ok(['ok', 'disabled', 'unavailable'].includes(source.usageIngestionStatus), 'source.usageIngestionStatus invalid')
+  assert.ok(['fresh', 'aging', 'stale', 'unknown', 'disabled', 'unavailable'].includes(source.usageFreshnessState), 'source.usageFreshnessState invalid')
+  assert.ok(['fresh', 'aging', 'stale', 'unknown', 'disabled', 'unavailable'].includes(source.usageActivityStatus), 'source.usageActivityStatus invalid')
+  assert.equal(typeof source.usageNearStale, 'boolean', 'source.usageNearStale must be boolean')
+  assert.equal(typeof source.usagePastStaleThreshold, 'boolean', 'source.usagePastStaleThreshold must be boolean')
+  assert.equal(typeof source.usageRefreshAttempted, 'boolean', 'source.usageRefreshAttempted must be boolean')
+  assert.equal(typeof source.usageRefreshRecovered, 'boolean', 'source.usageRefreshRecovered must be boolean')
+  assert.ok(Number.isInteger(source.usageRefreshAttempts) && source.usageRefreshAttempts >= 0, 'source.usageRefreshAttempts must be integer >= 0')
+  assert.ok(Number.isInteger(source.usageRefreshReprobes) && source.usageRefreshReprobes >= 0, 'source.usageRefreshReprobes must be integer >= 0')
+  assert.ok(Number.isFinite(source.usageRefreshDelayMs) && source.usageRefreshDelayMs >= 0, 'source.usageRefreshDelayMs must be number >= 0')
+  assert.ok(source.usageRefreshDurationMs === null || Number.isFinite(source.usageRefreshDurationMs), 'source.usageRefreshDurationMs must be number or null')
+  assert.equal(typeof source.usageRefreshOnNearStale, 'boolean', 'source.usageRefreshOnNearStale must be boolean')
+  assert.equal(typeof source.usageIdle, 'boolean', 'source.usageIdle must be boolean')
+  assert.ok(source.usageCommand === null || typeof source.usageCommand === 'string', 'source.usageCommand must be string or null')
+  assert.ok(['ok', 'fallback-cache', 'disabled', 'command-missing', 'command-error', 'parse-error', 'unavailable'].includes(source.usageProbeResult), 'source.usageProbeResult invalid')
+  assert.ok(Number.isInteger(source.usageProbeAttempts) && source.usageProbeAttempts >= 0, 'source.usageProbeAttempts must be integer >= 0')
+  assert.ok(source.usageProbeDurationMs === null || (Number.isFinite(source.usageProbeDurationMs) && source.usageProbeDurationMs >= 0), 'source.usageProbeDurationMs must be number or null')
+  assert.ok(Number.isInteger(source.usageProbeSweeps) && source.usageProbeSweeps >= 0, 'source.usageProbeSweeps must be integer >= 0')
+  assert.ok(Number.isInteger(source.usageProbeRetries) && source.usageProbeRetries >= 0, 'source.usageProbeRetries must be integer >= 0')
+  assert.ok(Number.isFinite(source.usageProbeTimeoutMs) && source.usageProbeTimeoutMs > 0, 'source.usageProbeTimeoutMs must be number > 0')
+  assert.ok(source.usageProbeError === null || typeof source.usageProbeError === 'string', 'source.usageProbeError must be string or null')
+  assert.equal(typeof source.usageUsedFallbackCache, 'boolean', 'source.usageUsedFallbackCache must be boolean')
+  assert.ok(source.usageFallbackCacheSource === null || ['memory', 'disk'].includes(source.usageFallbackCacheSource), 'source.usageFallbackCacheSource must be memory|disk|null')
+  assert.ok(['ok', 'notice', 'warning', 'critical', 'off'].includes(source.usageAlertLevel), 'source.usageAlertLevel invalid')
+  assert.ok(['healthy', 'activity-idle', 'activity-near-stale', 'activity-past-threshold', 'activity-stale', 'activity-no-new-usage', 'ingestion-unavailable', 'usage-disabled'].includes(source.usageAlertReason), 'source.usageAlertReason invalid')
+  assertNumberOrNull(source.usageFallbackCacheAgeMs, 'source.usageFallbackCacheAgeMs')
+  assert.ok(Number.isFinite(source.usageStaleMsThreshold), 'source.usageStaleMsThreshold must be number')
+  assert.ok(Number.isFinite(source.usageNearStaleMsThreshold), 'source.usageNearStaleMsThreshold must be number')
+  assert.ok(Number.isFinite(source.usageStaleGraceMs), 'source.usageStaleGraceMs must be number')
+  assert.ok(Number.isFinite(source.usageIdleAfterMsThreshold), 'source.usageIdleAfterMsThreshold must be number')
+  assert.ok(typeof source.memPressureSource === 'string', 'source.memPressureSource must be string')
+
+  assert.equal(row.fleet.usage.tokensPerMin, row.tokensPerMin, 'fleet usage tokensPerMin must mirror legacy field')
+  assert.equal(row.fleet.usage.totalTokens, row.openclawTotalTokens, 'fleet usage totalTokens must mirror legacy field')
+  assert.equal(row.fleet.usage.model, row.openclawModel, 'fleet usage model must mirror legacy field')
+  assert.equal(row.fleet.usage.sessionId, row.openclawSessionId, 'fleet usage sessionId must mirror legacy field')
+  assert.equal(row.fleet.usage.agentId, row.openclawAgentId, 'fleet usage.agentId must mirror legacy field')
+
+  if (source.usage === 'openclaw') {
+    assert.ok(row.openclawSessionId, 'openclawSessionId required when source.usage=openclaw')
+    assert.ok(row.openclawUsageTs, 'openclawUsageTs required when source.usage=openclaw')
+    assert.ok(source.usageFreshnessState, 'usageFreshnessState required when source.usage=openclaw')
+    assert.ok(['ok', 'fallback-cache'].includes(source.usageProbeResult), 'usageProbeResult must be ok or fallback-cache when source.usage=openclaw')
+    assert.equal(source.usageIngestionStatus, 'ok', 'usageIngestionStatus must be ok when source.usage=openclaw')
+    assert.ok(['fresh', 'aging', 'stale', 'unknown'].includes(source.usageActivityStatus), 'usageActivityStatus must reflect freshness when source.usage=openclaw')
+  }
+
+  if (source.usage === 'disabled') {
+    assert.equal(source.usageProbeResult, 'disabled', 'usageProbeResult must be disabled when source.usage=disabled')
+    assert.equal(source.usageIngestionStatus, 'disabled', 'usageIngestionStatus must be disabled when source.usage=disabled')
+    assert.equal(source.usageActivityStatus, 'disabled', 'usageActivityStatus must be disabled when source.usage=disabled')
+    assert.equal(source.usageFreshnessState, 'disabled', 'usageFreshnessState must be disabled when source.usage=disabled')
+    assert.equal(source.usageAlertLevel, 'off', 'usageAlertLevel must be off when source.usage=disabled')
+    assert.equal(source.usageAlertReason, 'usage-disabled', 'usageAlertReason must be usage-disabled when source.usage=disabled')
+  }
+
+  if (source.usageProbeAttempts === 0) {
+    assert.equal(source.usageProbeSweeps, 0, 'usageProbeSweeps must be 0 when no probe attempts ran')
+  } else {
+    assert.ok(source.usageProbeSweeps >= 1, 'usageProbeSweeps must be >= 1 when probe attempts run')
+  }
+  assert.ok(source.usageProbeSweeps <= source.usageProbeRetries + 1, 'usageProbeSweeps cannot exceed configured retries + 1')
+  if (source.usageRefreshRecovered) {
+    assert.equal(source.usageRefreshAttempted, true, 'usageRefreshRecovered implies usageRefreshAttempted')
+  }
+  if (source.usageRefreshAttempted) {
+    assert.ok(source.usageRefreshAttempts >= 1, 'usageRefreshAttempts must be >= 1 when refresh attempted')
+    assert.ok(source.usageRefreshAttempts <= source.usageRefreshReprobes + 1, 'usageRefreshAttempts cannot exceed configured reprobes + 1')
+  } else {
+    assert.equal(source.usageRefreshAttempts, 0, 'usageRefreshAttempts must be 0 when refresh not attempted')
+  }
+
+  if (source.usageAlertReason === 'activity-no-new-usage') {
+    assert.equal(source.usageIngestionStatus, 'ok', 'activity-no-new-usage requires ingestionStatus=ok')
+    assert.equal(source.usageActivityStatus, 'stale', 'activity-no-new-usage requires activityStatus=stale')
+    assert.equal(source.usageRefreshAttempted, true, 'activity-no-new-usage requires usageRefreshAttempted=true')
+    assert.equal(source.usageRefreshRecovered, false, 'activity-no-new-usage requires usageRefreshRecovered=false')
+  }
+
+  if (source.usage === 'unavailable') {
+    assert.ok(!['ok', 'fallback-cache'].includes(source.usageProbeResult), 'usageProbeResult must explain unavailable usage')
+    assert.ok(source.usageProbeAttempts > 0 || source.usageProbeResult === 'disabled', 'usageProbeAttempts should be > 0 when unavailable')
+    assert.equal(source.usageIngestionStatus, 'unavailable', 'usageIngestionStatus must be unavailable when source.usage=unavailable')
+    assert.equal(source.usageActivityStatus, 'unavailable', 'usageActivityStatus must be unavailable when source.usage=unavailable')
+    assert.equal(source.usageAlertLevel, 'critical', 'usageAlertLevel must be critical when source=unavailable')
+    assert.equal(source.usageAlertReason, 'ingestion-unavailable', 'usageAlertReason must be ingestion-unavailable when source=unavailable')
+  }
+
+  if (source.usageProbeResult === 'fallback-cache') {
+    assert.equal(source.usageUsedFallbackCache, true, 'usageUsedFallbackCache must be true for fallback-cache')
+    assert.ok(Number.isFinite(source.usageFallbackCacheAgeMs), 'usageFallbackCacheAgeMs required for fallback-cache')
+    assert.ok(['memory', 'disk'].includes(source.usageFallbackCacheSource), 'usageFallbackCacheSource required for fallback-cache')
+  } else {
+    assert.equal(source.usageUsedFallbackCache, false, 'usageUsedFallbackCache must be false unless fallback-cache')
+    assert.equal(source.usageFallbackCacheAgeMs, null, 'usageFallbackCacheAgeMs must be null unless fallback-cache')
+    assert.equal(source.usageFallbackCacheSource, null, 'usageFallbackCacheSource must be null unless fallback-cache')
+  }
+
+  if (source.usageIngestionStatus === 'ok') {
+    assert.ok(['ok', 'notice', 'warning'].includes(source.usageAlertLevel), 'ingestion ok cannot emit critical/off alert level')
+  }
+
+  if (REQUIRE_OPENCLAW_USAGE) {
+    assert.equal(source.usage, 'openclaw', 'IDLEWATCH_REQUIRE_OPENCLAW_USAGE=1 requires source.usage=openclaw')
+    assert.notEqual(source.usageIntegrationStatus, 'unavailable', 'OpenClaw usage must not be unavailable in strict mode')
+  }
+
+  if (MAX_OPENCLAW_USAGE_AGE_MS !== null && source.usage === 'openclaw') {
+    assert.ok(Number.isFinite(row.openclawUsageAgeMs), 'openclawUsageAgeMs must be present when enforcing max age')
+    assert.ok(
+      row.openclawUsageAgeMs <= MAX_OPENCLAW_USAGE_AGE_MS,
+      `openclawUsageAgeMs (${row.openclawUsageAgeMs}) exceeds max allowed ${MAX_OPENCLAW_USAGE_AGE_MS}`
+    )
+  }
+}
+
+try {
+  run()
+} catch (err) {
+  console.error(`dry-run schema validation failed: ${err.message}`)
+  process.exit(1)
+}

package/scripts/validate-onboarding.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } 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 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'
+  })
+
+  if (run.status !== 0) {
+    throw new Error(`quickstart failed\nstdout:\n${run.stdout}\nstderr:\n${run.stderr}`)
+  }
+
+  if (!fs.existsSync(envOut)) {
+    throw new Error('quickstart did not create output env file')
+  }
+
+  const envContent = fs.readFileSync(envOut, 'utf8')
+  if (!envContent.includes('FIREBASE_PROJECT_ID=idlewatch-test-project')) {
+    throw new Error('env file missing FIREBASE_PROJECT_ID')
+  }
+  if (!envContent.includes('FIREBASE_SERVICE_ACCOUNT_FILE=')) {
+    throw new Error('env file missing FIREBASE_SERVICE_ACCOUNT_FILE')
+  }
+
+  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')
+  }
+
+  console.log('onboarding validation passed')
+} finally {
+  fs.rmSync(tmpRoot, { recursive: true, force: true })
+}

package/scripts/validate-openclaw-cache-recovery-e2e.mjs

@@ -0,0 +1,113 @@
+#!/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 tempDir = mkdtempSync(join(tmpdir(), 'idlewatch-openclaw-cache-recover-'))
+const mockBinPath = join(tempDir, 'openclaw-mock.sh')
+const cachePath = join(tempDir, 'openclaw-last-good.json')
+const callLog = join(tempDir, 'calls.txt')
+const staleAgeMs = 90000
+const staleUsageTs = Date.now() - staleAgeMs
+
+function writeMockOpenClaw(path) {
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+calls_file="${callLog}"
+if [[ ! -f "$calls_file" ]]; then
+  echo 0 > "$calls_file"
+fi
+n=$(cat "$calls_file")
+next=$((n + 1))
+echo "$next" > "$calls_file"
+
+if [[ "$n" -lt 5 ]]; then
+  echo "openclaw temporary failure for recovery test" >&2
+  exit 1
+fi
+
+now_ms=$(node -p 'Date.now()')
+updated_at=$((now_ms - 2000))
+cat <<JSON
+{"sessions":{"defaults":{"model":"gpt-5.3-codex"},"recent":[{"sessionId":"cached-recover","agentId":"main","model":"gpt-5.3-codex","totalTokens":98765,"totalTokensFresh":true,"updatedAt":$updated_at,"updated_at":$updated_at}]},"ts":$now_ms}
+JSON
+`
+
+  writeFileSync(path, script, 'utf8')
+  chmodSync(path, 0o755)
+}
+
+function readRow(output) {
+  return readTelemetryJsonRow(output)
+}
+
+function run() {
+  const mockNow = Date.now()
+  const staleSnapshot = {
+    at: mockNow,
+    usage: {
+      model: 'gpt-5.3-codex',
+      totalTokens: 1111,
+      tokensPerMin: 45.0,
+      sessionId: 'cached-recover',
+      agentId: 'main',
+      usageTimestampMs: staleUsageTs,
+      sourceCommand: 'legacy-cache'
+    }
+  }
+
+  writeFileSync(cachePath, JSON.stringify(staleSnapshot), 'utf8')
+  writeMockOpenClaw(mockBinPath)
+
+  const env = {
+    ...process.env,
+    IDLEWATCH_OPENCLAW_BIN: mockBinPath,
+    IDLEWATCH_OPENCLAW_BIN_STRICT: '1',
+    IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH: cachePath,
+    IDLEWATCH_USAGE_STALE_MS: '60000',
+    IDLEWATCH_USAGE_STALE_GRACE_MS: '10000',
+    IDLEWATCH_USAGE_REFRESH_REPROBES: '1',
+    IDLEWATCH_USAGE_REFRESH_DELAY_MS: '0',
+    IDLEWATCH_OPENCLAW_PROBE_RETRIES: '0',
+    IDLEWATCH_USAGE_REFRESH_ON_NEAR_STALE: '1',
+    IDLEWATCH_INTERVAL_MS: '1000'
+  }
+
+  const out = execFileSync('node', ['bin/idlewatch-agent.js', '--dry-run'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  const row = readRow(out)
+  assert.equal(row?.source?.usage, 'openclaw', 'usage source should remain openclaw with fallback-cache path')
+  assert.equal(
+    row?.source?.usageProbeResult === 'fallback-cache' || row?.source?.usageProbeResult === 'ok',
+    true,
+    'expected fallback-cache or live probe result'
+  )
+  assert.equal(row?.source?.usageRefreshAttempted, true, 'stale cache path should trigger refresh attempts')
+  assert.equal(row?.source?.usageRefreshAttempts >= 1, true, 'expected at least one refresh attempt')
+
+  if (row?.source?.usageProbeResult === 'ok') {
+    assert.equal(row?.source?.usageFreshnessState, 'fresh', 'recovered probe should return fresh state')
+    assert.equal(row?.source?.usageRefreshRecovered, true, 'stale cache path should recover when probe succeeds')
+    assert.equal(row?.source?.usageAlertLevel, 'ok', 'activity should be healthy after recovery')
+  }
+
+  const calls = Number(readFileSync(callLog, 'utf8').trim())
+  assert.ok(Number.isFinite(calls) && calls >= 2, `expected mock probe called at least twice, got ${calls}`)
+
+  console.log('validate-openclaw-cache-recovery-e2e: ok (fallback-cache sample recovered via forced reprobe)')
+}
+
+try {
+  run()
+} finally {
+  rmSync(tempDir, { recursive: true, force: true })
+}

package/scripts/validate-openclaw-release-gates.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+
+const repoRoot = process.cwd()
+
+const RELEASE_GATE_TIMEOUT_MS = process.env.IDLEWATCH_DRY_RUN_TIMEOUT_MS || '60000'
+
+function shouldRequireOpenClaw(rawValue) {
+  const raw = String(rawValue ?? '1').trim().toLowerCase()
+  if (raw === '0' || raw === 'false' || raw === 'off' || raw === 'no') return false
+  if (raw === '1' || raw === 'true' || raw === 'on' || raw === 'yes') return true
+  return true
+}
+
+function runValidator(name, extraEnv = {}) {
+  const requireOpenClawUsage = shouldRequireOpenClaw(process.env.IDLEWATCH_REQUIRE_OPENCLAW_USAGE)
+  const requireOpenClaw = requireOpenClawUsage ? '1' : '0'
+
+  const result = spawnSync('npm', ['run', name, '--silent'], {
+    cwd: repoRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      IDLEWATCH_REQUIRE_OPENCLAW_USAGE: requireOpenClaw,
+      IDLEWATCH_DRY_RUN_TIMEOUT_MS: RELEASE_GATE_TIMEOUT_MS,
+      ...extraEnv
+    }
+  })
+
+  const out = String(result.stdout || '') + String(result.stderr || '')
+  if (result.status !== 0) {
+    if (out.trim()) {
+      console.error(out.trim())
+    }
+    console.error(`Validator ${name} failed with exit code ${result.status}`)
+    process.exit(result.status)
+  }
+
+  process.stdout.write(out)
+}
+
+function main() {
+  runValidator('validate:openclaw-usage-health')
+  runValidator('validate:openclaw-stats-ingestion')
+  runValidator('validate:openclaw-cache-recovery-e2e')
+
+  console.log('validate-openclaw-release-gates: ok (host OpenClaw checks for usage-health, stats fallback, and stale-cache recovery)')
+}
+
+main()