idlewatch 0.1.0

package/docs/telemetry/idle-stale-policy.md

@@ -0,0 +1,57 @@
+# OpenClaw Usage Staleness & Idle Policy
+
+## Overview
+
+When IdleWatch monitors OpenClaw usage via `openclaw status --json`, the
+`openclawUsageAgeMs` field reflects how long ago the most recent session
+activity occurred. During periods of user inactivity (no prompts, no agent
+turns), this age grows continuously.
+
+## Expected behavior during idle
+
+| Condition | `usageFreshnessState` | `usageAlertLevel` | `usageAlertReason` |
+|---|---|---|---|
+| Age < `IDLEWATCH_USAGE_NEAR_STALE_MS` | `fresh` | `ok` | `healthy` |
+| Age ≥ near-stale threshold | `fresh` (aging) | `ok` | `healthy` |
+| Age ≥ `IDLEWATCH_USAGE_STALE_MS` + grace | `stale` | `warning` | `activity-past-threshold` |
+| Age ≥ `IDLEWATCH_USAGE_IDLE_AFTER_MS` (6h default) | `stale` | `idle` | `idle-expected` |
+
+## Why stale/warning is normal during idle
+
+OpenClaw's `status --json` reports the timestamp of the **last session
+activity**. If no one is using the assistant, the age naturally grows past the
+stale threshold (default 60s + 10s grace). This does **not** indicate a
+monitoring failure — it indicates the assistant is simply idle.
+
+The `warning` alert level means "usage data is stale relative to the
+freshness SLO" — it is an **informational signal**, not an error. Operators
+should treat sustained `warning` during known idle windows (nights,
+weekends) as normal.
+
+## When to investigate
+
+- `warning` persisting during **active** usage sessions (the assistant is
+  being used but IdleWatch still reports stale) → probe or parse failure.
+- `usageIngestionStatus` is not `ok` → the probe itself is broken.
+- `usageProbeResult` shows `command-error` or `parse-error` → OpenClaw CLI
+  issue.
+
+## Thresholds
+
+| Env var | Default | Description |
+|---|---|---|
+| `IDLEWATCH_USAGE_STALE_MS` | `max(interval×3, 60000)` | Age beyond which usage is stale |
+| `IDLEWATCH_USAGE_NEAR_STALE_MS` | `floor((stale+grace)×0.85)` | Pre-stale aging signal |
+| `IDLEWATCH_USAGE_STALE_GRACE_MS` | `min(interval, 10000)` | Grace window before stale alert |
+| `IDLEWATCH_USAGE_IDLE_AFTER_MS` | `21600000` (6h) | Downgrade stale→idle after this age |
+| `IDLEWATCH_MAX_OPENCLAW_USAGE_AGE_MS` | `600000` (10m) | SLO validator threshold |
+
+## Dashboard guidance
+
+- Filter alerts: suppress `warning` when `usageAlertReason` is
+  `activity-past-threshold` during off-hours.
+- Use `idle` alert level (after 6h) as a positive signal that the host is
+  inactive rather than broken.
+- Key reliability signals: `usageIngestionStatus` and `usageProbeResult`.
+  If both are `ok`, the monitoring pipeline is healthy regardless of
+  freshness state.

package/docs/telemetry/openclaw-mapping.md

@@ -0,0 +1,80 @@
+# OpenClaw Telemetry Mapping for Fleet Aggregation
+
+## Purpose
+
+This spec defines a stable, versioned OpenClaw-focused telemetry envelope for fleet dashboards while preserving the existing flat IdleWatch row shape.
+
+## Goals
+
+- Keep existing flat fields fully backward compatible.
+- Add a canonical `fleet` object for aggregation across hosts.
+- Carry explicit provenance so operators can trust/triage usage data.
+- Version the schema to support additive evolution.
+
+## Schema contract (v1)
+
+- `schemaFamily`: `idlewatch.openclaw.fleet`
+- `schemaVersion`: `1.0.0`
+- `schemaCompat`: `["0.x-flat-row"]`
+
+### Backward compatibility
+
+All prior top-level fields are retained (`cpuPct`, `memPct`, `tokensPerMin`, `openclaw*`, `source.*`, etc.).
+Consumers using old selectors continue to work.
+
+## Canonical mapping
+
+### Fleet identity
+
+- `fleet.host` ← `host`
+- `fleet.collectedAtMs` ← `ts`
+
+### Fleet resources (high-value host load)
+
+- `fleet.resources.cpuPct` ← `cpuPct`
+- `fleet.resources.memUsedPct` ← `memUsedPct` (fallback `memPct`)
+- `fleet.resources.memPressurePct` ← `memPressurePct`
+- `fleet.resources.memPressureClass` ← `memPressureClass`
+
+### Fleet usage (OpenClaw)
+
+- `fleet.usage.model` ← `openclawModel`
+- `fleet.usage.totalTokens` ← `openclawTotalTokens`
+- `fleet.usage.tokensPerMin` ← `tokensPerMin`
+- `fleet.usage.sessionId` ← `openclawSessionId`
+- `fleet.usage.agentId` ← `openclawAgentId`
+- `fleet.usage.usageTimestampMs` ← `openclawUsageTs`
+- `fleet.usage.usageAgeMs` ← `openclawUsageAgeMs`
+- `fleet.usage.freshnessState` ← `source.usageFreshnessState`
+- `fleet.usage.integrationStatus` ← `source.usageIntegrationStatus`
+- `fleet.usage.ingestionStatus` ← `source.usageIngestionStatus`
+- `fleet.usage.activityStatus` ← `source.usageActivityStatus`
+- `fleet.usage.alertLevel` ← `source.usageAlertLevel`
+- `fleet.usage.alertReason` ← `source.usageAlertReason`
+
+### Provenance
+
+- `fleet.provenance.collector` ← static `idlewatch-agent`
+- `fleet.provenance.collectorVersion` ← package version
+- `fleet.provenance.usageSource` ← `source.usage`
+- `fleet.provenance.usageCommand` ← `source.usageCommand`
+- `fleet.provenance.usageProbeResult` ← `source.usageProbeResult`
+- `fleet.provenance.usageProbeAttempts` ← `source.usageProbeAttempts`
+- `fleet.provenance.usageUsedFallbackCache` ← `source.usageUsedFallbackCache`
+- `fleet.provenance.usageFallbackCacheSource` ← `source.usageFallbackCacheSource`
+
+## Enrichment rollout plan
+
+1. Emit `schemaFamily/schemaVersion/schemaCompat` + `fleet` object (additive only).
+2. Keep legacy flat fields indefinitely during migration.
+3. Dashboards/alerts migrate to `fleet.*` paths by domain:
+   - capacity: `fleet.resources.*`
+   - usage: `fleet.usage.*`
+   - reliability: `fleet.provenance.*` + `fleet.usage.ingestionStatus`
+4. Future changes are additive under v1; breaking path changes require v2.
+
+## Fixtures and tests
+
+- Fixture sample: `test/fixtures/openclaw-fleet-sample-v1.json`
+- Mapping unit tests: `test/telemetry-mapping.test.mjs`
+- Dry-run schema gate includes v1 checks: `scripts/validate-dry-run-schema.mjs`

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "idlewatch",
+  "version": "0.1.0",
+  "description": "Host telemetry collector for IdleWatch",
+  "type": "module",
+  "bin": {
+    "idlewatch": "bin/idlewatch-agent.js",
+    "idlewatch-agent": "bin/idlewatch-agent.js",
+    "idlewatch-skill": "bin/idlewatch-agent.js"
+  },
+  "scripts": {
+    "start": "node bin/idlewatch-agent.js",
+    "quickstart": "node bin/idlewatch-agent.js quickstart",
+    "validate:bin": "node scripts/validate-bin.mjs",
+    "validate:onboarding": "node scripts/validate-onboarding.mjs",
+    "test:unit": "node --test 'test/*.test.mjs'",
+    "smoke:help": "node bin/idlewatch-agent.js --help",
+    "smoke:dry-run": "node bin/idlewatch-agent.js --dry-run",
+    "smoke:once": "IDLEWATCH_OPENCLAW_USAGE=off node bin/idlewatch-agent.js --once",
+    "validate:dry-run-schema": "node scripts/validate-dry-run-schema.mjs node bin/idlewatch-agent.js --dry-run",
+    "validate:packaged-dry-run-schema": "[ \"${IDLEWATCH_SKIP_PACKAGE_MACOS:-}\" = \"1\" ] || npm run package:macos --silent && node scripts/validate-dry-run-schema.mjs ./dist/IdleWatch.app/Contents/MacOS/IdleWatch --dry-run",
+    "validate:packaged-dry-run-schema:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-dry-run-schema --silent",
+    "validate:packaged-usage-health": "[ \"${IDLEWATCH_SKIP_PACKAGE_MACOS:-}\" = \"1\" ] || npm run package:macos --silent && IDLEWATCH_REQUIRE_OPENCLAW_USAGE=1 node scripts/validate-dry-run-schema.mjs ./dist/IdleWatch.app/Contents/MacOS/IdleWatch --dry-run",
+    "validate:packaged-usage-health:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-health --silent",
+    "validate:packaged-usage-age-slo": "[ \"${IDLEWATCH_SKIP_PACKAGE_MACOS:-}\" = \"1\" ] || npm run package:macos --silent && IDLEWATCH_REQUIRE_OPENCLAW_USAGE=1 IDLEWATCH_MAX_OPENCLAW_USAGE_AGE_MS=600000 node scripts/validate-dry-run-schema.mjs ./dist/IdleWatch.app/Contents/MacOS/IdleWatch --dry-run",
+    "validate:packaged-usage-age-slo:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-age-slo --silent",
+    "validate:firebase-emulator-mode": "FIREBASE_PROJECT_ID=idlewatch-dev FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 IDLEWATCH_OPENCLAW_USAGE=off node bin/idlewatch-agent.js --dry-run",
+    "validate:firebase-write-once": "IDLEWATCH_OPENCLAW_USAGE=off node bin/idlewatch-agent.js --once",
+    "validate:firebase-write-required-once": "IDLEWATCH_REQUIRE_FIREBASE_WRITES=1 IDLEWATCH_OPENCLAW_USAGE=off node bin/idlewatch-agent.js --once",
+    "validate:dmg-install": "./scripts/validate-dmg-install.sh",
+    "validate:packaged-bundled-runtime": "./scripts/validate-packaged-bundled-runtime.sh",
+    "validate:packaged-bundled-runtime:reuse-artifact": "IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-bundled-runtime --silent",
+    "validate:dmg-checksum": "./scripts/validate-dmg-checksum.sh",
+    "validate:usage-freshness-e2e": "node scripts/validate-usage-freshness-e2e.mjs",
+    "validate:usage-alert-rate-e2e": "node scripts/validate-usage-alert-rate-e2e.mjs",
+    "validate:packaged-usage-recovery-e2e": "node scripts/validate-packaged-usage-recovery-e2e.mjs",
+    "validate:packaged-usage-alert-rate-e2e": "node scripts/validate-packaged-usage-alert-rate-e2e.mjs",
+    "validate:openclaw-cache-recovery-e2e": "node scripts/validate-openclaw-cache-recovery-e2e.mjs",
+    "validate:openclaw-stats-ingestion": "node scripts/validate-openclaw-stats-ingestion.mjs",
+    "validate:openclaw-usage-health": "node scripts/validate-openclaw-usage-health.mjs",
+    "validate:packaged-usage-probe-noise-e2e": "node scripts/validate-packaged-usage-probe-noise-e2e.mjs",
+    "validate:packaged-openclaw-stats-ingestion": "node scripts/validate-packaged-openclaw-stats-ingestion.mjs",
+    "validate:packaged-openclaw-cache-recovery-e2e": "node scripts/validate-packaged-openclaw-cache-recovery-e2e.mjs",
+    "validate:trusted-prereqs": "./scripts/validate-trusted-prereqs.sh",
+    "package:macos": "./scripts/package-macos.sh",
+    "package:dmg": "./scripts/build-dmg.sh",
+    "validate:packaged-metadata": "./scripts/validate-packaged-metadata.sh",
+    "package:trusted": "IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1 npm run validate:trusted-prereqs --silent && IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1 ./scripts/package-macos.sh && IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1 ./scripts/build-dmg.sh",
+    "package:release": "npm run package:trusted && npm run validate:dmg-checksum",
+    "install:macos-launch-agent": "./scripts/install-macos-launch-agent.sh",
+    "uninstall:macos-launch-agent": "./scripts/uninstall-macos-launch-agent.sh",
+    "test": "npm run validate:bin && npm run test:unit && npm run smoke:help && npm run smoke:dry-run && npm run smoke:once",
+    "validate:all": "./scripts/validate-all.sh",
+    "validate:all:quick": "./scripts/validate-all.sh --skip-packaging",
+    "validate:packaged-openclaw-release-gates": "node scripts/validate-packaged-openclaw-release-gates.mjs",
+    "validate:openclaw-release-gates": "node scripts/validate-openclaw-release-gates.mjs",
+    "validate:openclaw-release-gates:all": "npm run validate:openclaw-release-gates --silent && if [ \"$(uname -s)\" = \"Darwin\" ]; then npm run validate:packaged-openclaw-release-gates:reuse-artifact --silent; fi",
+    "validate:packaged-openclaw-release-gates:all": "npm run validate:packaged-openclaw-release-gates --silent && npm run validate:packaged-openclaw-release-gates:reuse-artifact --silent",
+    "validate:packaged-openclaw-robustness": "npm run validate:packaged-usage-age-slo --silent && npm run validate:packaged-usage-alert-rate-e2e --silent && npm run validate:packaged-usage-probe-noise-e2e --silent && npm run validate:packaged-openclaw-release-gates --silent",
+    "validate:packaged-openclaw-robustness:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-age-slo --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-alert-rate-e2e --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-probe-noise-e2e --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-openclaw-release-gates --silent",
+    "validate:packaged-openclaw-release-gates:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-openclaw-release-gates --silent",
+    "validate:packaged-openclaw-cache-recovery-e2e:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-openclaw-cache-recovery-e2e --silent",
+    "validate:packaged-openclaw-stats-ingestion:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-openclaw-stats-ingestion --silent",
+    "validate:packaged-usage-recovery-e2e:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-recovery-e2e --silent",
+    "validate:packaged-usage-probe-noise-e2e:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-probe-noise-e2e --silent",
+    "validate:packaged-usage-alert-rate-e2e:reuse-artifact": "npm run validate:packaged-artifact --silent && IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:packaged-usage-alert-rate-e2e --silent",
+    "validate:openclaw-release-gates:reuse-artifact": "IDLEWATCH_SKIP_PACKAGE_MACOS=1 npm run validate:openclaw-release-gates --silent",
+    "validate:release-gate-all": "npm run validate:openclaw-release-gates:all --silent && if [ \"$(uname -s)\" = \"Darwin\" ]; then npm run validate:packaged-openclaw-robustness --silent; fi",
+    "validate:release-gate": "npm run validate:openclaw-release-gates --silent && if [ \"$(uname -s)\" = \"Darwin\" ]; then npm run validate:packaged-openclaw-robustness:reuse-artifact --silent; fi",
+    "validate:packaged-artifact": "node scripts/validate-packaged-artifact.mjs",
+    "validate:packaged-artifact:bundled-runtime": "IDLEWATCH_REQUIRE_NODE_RUNTIME_BUNDLED=1 npm run validate:packaged-artifact --silent"
+  },
+  "dependencies": {
+    "firebase-admin": "^12.7.0"
+  }
+}

package/scripts/build-dmg.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DIST_DIR="$ROOT_DIR/dist"
+DMG_ROOT="$DIST_DIR/dmg-root"
+VERSION="$(node -p "require('./package.json').version" 2>/dev/null || node -e "import('./package.json',{with:{type:'json'}}).then(m=>console.log(m.default.version))")"
+NOTARY_PROFILE="${MACOS_NOTARY_PROFILE:-}"
+REQUIRE_TRUSTED="${IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION:-0}"
+ALLOW_UNSIGNED_TAG_RELEASE="${IDLEWATCH_ALLOW_UNSIGNED_TAG_RELEASE:-0}"
+if [[ "$REQUIRE_TRUSTED" != "1" && "${GITHUB_ACTIONS:-}" == "true" ]]; then
+  REF_NAME="${GITHUB_REF:-}"
+  REF_TYPE="${GITHUB_REF_TYPE:-}"
+  if [[ "$REF_TYPE" == "tag" || "$REF_NAME" == refs/tags/* ]]; then
+    if [[ "$ALLOW_UNSIGNED_TAG_RELEASE" != "1" ]]; then
+      REQUIRE_TRUSTED="1"
+      echo "Detected CI tag build; enforcing trusted distribution requirements (set IDLEWATCH_ALLOW_UNSIGNED_TAG_RELEASE=1 to bypass intentionally)."
+    fi
+  fi
+fi
+DMG_SUFFIX="unsigned"
+if [[ -n "${MACOS_CODESIGN_IDENTITY:-}" ]]; then
+  DMG_SUFFIX="signed"
+fi
+
+if [[ "$REQUIRE_TRUSTED" == "1" ]]; then
+  if [[ "$DMG_SUFFIX" != "signed" ]]; then
+    echo "IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1 requires MACOS_CODESIGN_IDENTITY to be set." >&2
+    exit 1
+  fi
+  if [[ -z "$NOTARY_PROFILE" ]]; then
+    echo "IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1 requires MACOS_NOTARY_PROFILE to be set." >&2
+    exit 1
+  fi
+fi
+OUT_DMG="$DIST_DIR/IdleWatch-${VERSION}-${DMG_SUFFIX}.dmg"
+
+if [[ ! -d "$DMG_ROOT" ]]; then
+  echo "Missing $DMG_ROOT. Run ./scripts/package-macos.sh first." >&2
+  exit 1
+fi
+
+rm -f "$OUT_DMG"
+
+hdiutil create \
+  -volname "IdleWatch" \
+  -srcfolder "$DMG_ROOT" \
+  -ov \
+  -format UDZO \
+  "$OUT_DMG"
+
+if command -v shasum >/dev/null 2>&1; then
+  shasum -a 256 "$OUT_DMG" > "$OUT_DMG.sha256"
+  echo "Wrote checksum: $OUT_DMG.sha256"
+fi
+
+if [[ -n "$NOTARY_PROFILE" ]]; then
+  echo "Submitting DMG for notarization with profile: $NOTARY_PROFILE"
+  xcrun notarytool submit "$OUT_DMG" --keychain-profile "$NOTARY_PROFILE" --wait
+  xcrun stapler staple "$OUT_DMG"
+  echo "Created notarized DMG: $OUT_DMG"
+else
+  echo "Created DMG: $OUT_DMG"
+  echo "MACOS_NOTARY_PROFILE not set; skipped notarization/staple."
+fi

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_PATH="${IDLEWATCH_APP_PATH:-/Applications/IdleWatch.app}"
+BIN_PATH="${IDLEWATCH_APP_BIN:-$APP_PATH/Contents/MacOS/IdleWatch}"
+PLIST_LABEL="${IDLEWATCH_LAUNCH_AGENT_LABEL:-com.idlewatch.agent}"
+PLIST_ROOT="${IDLEWATCH_LAUNCH_AGENT_PLIST_ROOT:-$HOME/Library/LaunchAgents}"
+LOG_DIR="${IDLEWATCH_LAUNCH_AGENT_LOG_DIR:-$HOME/Library/Logs/IdleWatch}"
+INTERVAL_MS="${IDLEWATCH_INTERVAL_MS:-10000}"
+START_INTERVAL_SEC=$(( (INTERVAL_MS / 1000) ))
+if [[ $START_INTERVAL_SEC -lt 60 ]]; then
+  START_INTERVAL_SEC=60
+fi
+
+PLIST_PATH="$PLIST_ROOT/$PLIST_LABEL.plist"
+
+if [[ ! -d "$PLIST_ROOT" ]]; then
+  mkdir -p "$PLIST_ROOT"
+fi
+
+if [[ ! -d "$LOG_DIR" ]]; then
+  mkdir -p "$LOG_DIR"
+fi
+
+if ! command -v launchctl >/dev/null 2>&1; then
+  echo "launchctl not available; this script must be run on macOS." >&2
+  exit 1
+fi
+
+if [[ ! -x "$BIN_PATH" ]]; then
+  echo "IdleWatch launcher executable not found or not executable: $BIN_PATH" >&2
+  echo "Set IDLEWATCH_APP_BIN to the correct binary path before running this script." >&2
+  exit 1
+fi
+
+cat > "$PLIST_PATH" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>{{PLIST_LABEL}}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{BIN_PATH}}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>{{LOG_DIR}}/idlewatch.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{LOG_DIR}}/idlewatch.err.log</string>
+  <key>StartInterval</key>
+  <integer>{{START_INTERVAL_SEC}}</integer>
+</dict>
+</plist>
+PLIST
+
+sed -i '' "s|{{PLIST_LABEL}}|$PLIST_LABEL|g" "$PLIST_PATH"
+sed -i '' "s|{{BIN_PATH}}|$BIN_PATH|g" "$PLIST_PATH"
+sed -i '' "s|{{LOG_DIR}}|$LOG_DIR|g" "$PLIST_PATH"
+sed -i '' "s|{{START_INTERVAL_SEC}}|$START_INTERVAL_SEC|g" "$PLIST_PATH"
+
+USER_GUID="$(id -u)"
+PLIST_ID="gui/$USER_GUID/$PLIST_LABEL"
+if launchctl print "$PLIST_ID" >/dev/null 2>&1; then
+  echo "LaunchAgent already loaded. Replacing configuration for $PLIST_ID."
+  launchctl bootout "$PLIST_ID" || true
+fi
+
+launchctl bootstrap "gui/$USER_GUID" "$PLIST_PATH"
+launchctl enable "$PLIST_ID"
+echo "Installed LaunchAgent: $PLIST_ID"
+echo "Plist: $PLIST_PATH"

package/scripts/lib/telemetry-row-parser.mjs

@@ -0,0 +1,100 @@
+export function stripControlNoise(raw) {
+  return String(raw)
+    .replace(/\x1b\][^\x07\x1b]*\x07/g, '')
+    .replace(/\x1b\][^\x07\x1b]*\x1b\\/g, '')
+    .replace(/\x9b\][^\x07\x1b]*\x07/g, '')
+    .replace(/\x9b[^\x07\x1b]*\x1b\\/g, '')
+    .replace(/\x1b[PXZ^_].*?(?:\x1b\\|\x9c)/gs, '')
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .replace(new RegExp(`\x1b[^m]*m`, 'g'), '')
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+    .replace(/\r/g, '')
+}
+
+export function extractJsonCandidates(raw) {
+  const text = stripControlNoise(raw)
+  const candidates = []
+
+  for (let start = 0; start < text.length; start += 1) {
+    const open = text[start]
+    if (open !== '{' && open !== '[') continue
+    if (open === '[') {
+      const rest = text.slice(start + 1)
+      const firstToken = rest.match(/^\s*([\[{])/)
+      if (!firstToken) continue
+    }
+
+    const close = open === '{' ? '}' : ']'
+    let depth = 0
+    let inString = false
+    let escaped = false
+    let end = -1
+
+    for (let i = start; i < text.length; i++) {
+      const ch = text[i]
+
+      if (inString) {
+        if (escaped) {
+          escaped = false
+          continue
+        }
+        if (ch === '\\') {
+          escaped = true
+          continue
+        }
+        if (ch === '"') {
+          inString = false
+          continue
+        }
+        continue
+      }
+
+      if (ch === '"') {
+        inString = true
+        continue
+      }
+
+      if (ch === open) {
+        depth += 1
+        continue
+      }
+
+      if (ch === close) {
+        depth -= 1
+        if (depth === 0) {
+          end = i
+          break
+        }
+
+        if (depth < 0) {
+          break
+        }
+      }
+    }
+
+    if (end > start) {
+      candidates.push(text.slice(start, end + 1))
+      start = end
+    }
+  }
+
+  return candidates
+}
+
+export function readTelemetryJsonRow(raw) {
+  const candidates = extractJsonCandidates(raw)
+  let lastErr
+
+  for (let i = candidates.length - 1; i >= 0; i -= 1) {
+    try {
+      return JSON.parse(candidates[i])
+    } catch (err) {
+      lastErr = err
+    }
+  }
+
+  const message = `No telemetry JSON row found in command output (${candidates.length} JSON candidates)`
+  const error = new Error(message)
+  if (lastErr) error.cause = lastErr
+  throw error
+}