@rubytech/create-maxy-code 0.1.233 → 0.1.234

package/dist/__tests__/cloudflared-slice.test.js

@@ -0,0 +1,19 @@
+// Task 602 — cloudflared.slice unit emitted at install time.
+// Every cloudflared-<brand>.scope spawned by resume-tunnel.sh drops under
+// this slice for cohort observability via `systemctl --user status cloudflared.slice`.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildCloudflaredSliceUnitFile } from "../port-resolution.js";
+test("buildCloudflaredSliceUnitFile emits a valid systemd slice unit", () => {
+    const unit = buildCloudflaredSliceUnitFile();
+    assert.match(unit, /^\[Unit\]$/m);
+    assert.match(unit, /^Description=Cloudflare tunnel scopes \(Task 602\)$/m);
+    assert.match(unit, /^\[Slice\]$/m);
+    assert.match(unit, /^\[Install\]$/m);
+    assert.match(unit, /^WantedBy=default\.target$/m);
+});
+test("buildCloudflaredSliceUnitFile output has no per-brand template tokens", () => {
+    const unit = buildCloudflaredSliceUnitFile();
+    assert.doesNotMatch(unit, /\$\{/);
+    assert.doesNotMatch(unit, /__[A-Z_]+__/);
+});

package/dist/index.js

@@ -5,7 +5,7 @@ import { registerSpecialistAgentsAt, SpecialistSymlinkCollision } from "./specia
 import { seedBypassPermissionsSettings, assertBypassPermissionsSeed } from "./permissions-seed.js";
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
-import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile, buildClaudePtysSliceUnitFile } from "./port-resolution.js";
+import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile, buildClaudePtysSliceUnitFile, buildCloudflaredSliceUnitFile } from "./port-resolution.js";
 import { validateTierFlag, validateEntitlementBase64, applyTierToAccountConfig, entitlementPath } from "./tier-flag.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
@@ -3120,6 +3120,12 @@ function installService() {
     const claudePtysSliceName = "claude-ptys.slice";
     writeFileSync(join(serviceDir, claudePtysSliceName), buildClaudePtysSliceUnitFile());
     logFile(`  ${claudePtysSliceName}: Task 250 slice for claude-session-*.scope cohort`);
+    // Task 602 — write the brand-agnostic `cloudflared.slice` unit. Every
+    // cloudflared-<brand>.scope spawned by resume-tunnel.sh drops under this
+    // slice. Writing once per install is idempotent; daemon-reload below picks it up.
+    const cloudflaredSliceName = "cloudflared.slice";
+    writeFileSync(join(serviceDir, cloudflaredSliceName), buildCloudflaredSliceUnitFile());
+    logFile(`  ${cloudflaredSliceName}: Task 602 slice for cloudflared-*.scope cohort`);
     // Task 600 — per-brand RSS sampler: a long-running user service that
     // periodically writes per-claude.exe RSS + aggregate RSS to disk.
     // Named per-brand (BRAND.hostname prefix) so two brands on the same

package/dist/port-resolution.js

@@ -186,3 +186,23 @@ Before=shutdown.target
 WantedBy=default.target
 `;
 }
+// ---------------------------------------------------------------------------
+// Task 602 — `cloudflared.slice` unit. Every cloudflared-<brand>.scope
+// spawned by resume-tunnel.sh drops under this slice for one-glance cohort
+// observability (`systemctl --user status cloudflared.slice`).
+//
+// Brand-agnostic: one slice across all co-resident brands, mirroring the
+// Task-250 claude-ptys.slice precedent.
+// ---------------------------------------------------------------------------
+export function buildCloudflaredSliceUnitFile() {
+    return `[Unit]
+Description=Cloudflare tunnel scopes (Task 602)
+Documentation=https://github.com/rubytech/maxy-code/blob/main/.tasks/archive/602-cloudflared-tunnel-must-survive-brand-service-restart-via-systemd-scope.md
+Before=shutdown.target
+
+[Slice]
+
+[Install]
+WantedBy=default.target
+`;
+}

package/dist/uninstall.js

@@ -181,21 +181,24 @@ function stopServices() {
     catch {
         console.log(`  ${neo4jService} not running`);
     }
-    // Kill cloudflared (read PID from this brand's tunnel.state only).
-    // Never read ~/.cloudflared/ — that path is shared with every brand installed
-    // on this device plus cloudflared's own runtime-generated files.
-    const brandStateFile = join(CONFIG_DIR, "cloudflared/tunnel.state");
-    if (existsSync(brandStateFile)) {
-        try {
-            const state = JSON.parse(readFileSync(brandStateFile, "utf-8"));
-            if (state.pid) {
-                spawnSync("kill", [String(state.pid)], { stdio: "pipe" });
-                console.log(`  Killed cloudflared (PID ${state.pid})`);
-            }
-        }
-        catch {
-            console.log("  cloudflared not running");
-        }
+    // Stop the cloudflared scope for this brand. The scope unit name mirrors
+    // what resume-tunnel.sh derives: strip leading dot from configDir.
+    // BRAND.configDir is ".maxy-code"; strip the dot → "maxy-code".
+    // --no-block: uninstall does not wait for graceful shutdown of the tunnel.
+    // Exit 5 (no such unit) = scope absent = success.
+    const brand = BRAND.configDir.replace(/^\./, "");
+    const scopeUnit = `cloudflared-${brand}.scope`;
+    const stopResult = spawnSync("systemctl", ["--user", "stop", "--no-block", scopeUnit], { stdio: "pipe" });
+    if (stopResult.status === 0) {
+        console.log(`  Stopped ${scopeUnit}`);
+    }
+    else if (stopResult.status === 5) {
+        // exit 5 = unit not found — scope already absent, which is expected
+        console.log(`  ${scopeUnit} not running (scope absent)`);
+    }
+    else {
+        // Any other non-zero exit means systemctl itself failed (e.g. DBus unavailable)
+        console.log(`  systemctl stop ${scopeUnit} exited ${stopResult.status} — scope may still be running`);
     }
     // Brand isolation: the VNC stack and Ollama daemon are
     // device-wide singletons. Killing them during uninstall would interrupt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.233",
+  "version": "0.1.234",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/scripts/__tests__/resume-tunnel.test.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# Tests for resume-tunnel.sh scope-based spawn path (Task 602).
+# Stubs systemd-run, systemctl, and cloudflared binaries via a fake $PATH entry.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RESUME="$SCRIPT_DIR/../resume-tunnel.sh"
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1"; shift
+  echo ""
+  echo "=== CASE: $name ==="
+  if "$@"; then
+    PASS=$((PASS + 1))
+    echo "PASS: $name"
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: $name"
+  fi
+}
+
+# Build a minimal install tree with stubs and state file.
+# Args: root config_dir scope_active connect_success
+setup() {
+  local root="$1"
+  local config_dir="${2:-.maxy-code}"
+  local scope_active="${3:-inactive}"
+  local connect_success="${4:-yes}"
+
+  local home_dir="$root/home"
+  local platform_root="$root/platform_root"
+  local bin_dir="$root/bin"
+  mkdir -p "$home_dir/$config_dir/cloudflared" \
+           "$home_dir/$config_dir/logs" \
+           "$platform_root/config" \
+           "$bin_dir"
+
+  cat > "$platform_root/config/brand.json" <<JSON
+{"configDir": "$config_dir"}
+JSON
+
+  cat > "$home_dir/$config_dir/cloudflared/tunnel.state" <<JSON
+{
+  "tunnelId": "test-tunnel-id",
+  "domain": "test.example.com",
+  "configPath": "$home_dir/$config_dir/cloudflared/config.yml",
+  "pid": 99999
+}
+JSON
+
+  touch "$home_dir/$config_dir/cloudflared/cert.pem"
+  touch "$home_dir/$config_dir/cloudflared/config.yml"
+
+  local log_file="$home_dir/$config_dir/logs/cloudflared.log"
+
+  # Stub cloudflared: does nothing.
+  cat > "$bin_dir/cloudflared" <<'SH'
+#!/bin/bash
+sleep 0.1
+SH
+  chmod +x "$bin_dir/cloudflared"
+
+  # Stub systemctl: is-active returns based on scope_active.
+  cat > "$bin_dir/systemctl" <<SH
+#!/bin/bash
+if [[ "\$*" == *"is-active"* ]]; then
+  if [[ "${scope_active}" == "active" ]]; then
+    echo "active"; exit 0
+  else
+    echo "inactive"; exit 3
+  fi
+fi
+if [[ "\$*" == *"--property=MainPID"* ]]; then
+  echo "12345"
+fi
+exit 0
+SH
+  chmod +x "$bin_dir/systemctl"
+
+  # Stub systemd-run: logs its --unit= and --slice= args, optionally writes connection line.
+  cat > "$bin_dir/systemd-run" <<SH
+#!/bin/bash
+for arg in "\$@"; do
+  case "\$arg" in
+    --unit=*) echo "[stub] unit=\${arg#--unit=}" ;;
+    --slice=*) echo "[stub] slice=\${arg#--slice=}" ;;
+  esac
+done
+if [[ "${connect_success}" == "yes" ]]; then
+  echo "2026-06-02T00:00:00Z INF Registered tunnel connection connIndex=0" >> "${log_file}"
+fi
+exit 0
+SH
+  chmod +x "$bin_dir/systemd-run"
+}
+
+cleanup() { rm -rf "$1"; }
+
+# CASE 1: skip branch — scope is active
+case_skip_when_scope_active() {
+  local root
+  root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "active" "yes"
+
+  local log="$root/home/.maxy-code/logs/cloudflared.log"
+
+  HOME="$root/home" \
+  PATH="$root/bin:$PATH" \
+  MAXY_PLATFORM_ROOT="$root/platform_root" \
+    bash "$RESUME"
+  local rc=$?
+
+  local log_content
+  log_content=$(cat "$log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  if [[ $rc -ne 0 ]]; then
+    echo "  expected exit 0, got $rc"; return 1
+  fi
+  if ! echo "$log_content" | grep -q "already running.*scope.*cloudflared-maxy-code"; then
+    echo "  skip branch missing expected log line"
+    echo "$log_content"
+    return 1
+  fi
+  return 0
+}
+
+# CASE 2: spawn branch — scope inactive, connection succeeds
+case_spawn_succeeds() {
+  local root
+  root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "yes"
+
+  local log="$root/home/.maxy-code/logs/cloudflared.log"
+
+  HOME="$root/home" \
+  PATH="$root/bin:$PATH" \
+  MAXY_PLATFORM_ROOT="$root/platform_root" \
+    bash "$RESUME"
+  local rc=$?
+
+  local log_content
+  log_content=$(cat "$log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  if [[ $rc -ne 0 ]]; then
+    echo "  expected exit 0, got $rc"; return 1
+  fi
+  if ! echo "$log_content" | grep -q "spawned scope=cloudflared-maxy-code.scope"; then
+    echo "  missing spawned scope log line"; echo "$log_content"; return 1
+  fi
+  if ! echo "$log_content" | grep -q "tunnel verified"; then
+    echo "  missing tunnel verified log line"; echo "$log_content"; return 1
+  fi
+  return 0
+}
+
+# CASE 3: spawn branch — no edge connection within timeout
+case_spawn_no_connection() {
+  local root
+  root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "no"
+
+  local log="$root/home/.maxy-code/logs/cloudflared.log"
+
+  HOME="$root/home" \
+  PATH="$root/bin:$PATH" \
+  MAXY_PLATFORM_ROOT="$root/platform_root" \
+  RESUME_TUNNEL_VERIFY_DEADLINE=2 \
+    bash "$RESUME"
+  local rc=$?
+
+  local log_content
+  log_content=$(cat "$log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  if [[ $rc -ne 0 ]]; then
+    echo "  expected exit 0 even on failure, got $rc"; return 1
+  fi
+  if ! echo "$log_content" | grep -q "ERROR.*no edge connection"; then
+    echo "  missing ERROR log line on connection failure"; echo "$log_content"; return 1
+  fi
+  return 0
+}
+
+# CASE 4: scope unit name derived correctly from configDir (.real-agent → cloudflared-real-agent.scope)
+case_scope_unit_name_from_config_dir() {
+  local root
+  root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".real-agent" "inactive" "yes"
+
+  local log="$root/home/.real-agent/logs/cloudflared.log"
+
+  HOME="$root/home" \
+  PATH="$root/bin:$PATH" \
+  MAXY_PLATFORM_ROOT="$root/platform_root" \
+    bash "$RESUME"
+  local rc=$?
+
+  local log_content
+  log_content=$(cat "$log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  if [[ $rc -ne 0 ]]; then
+    echo "  expected exit 0, got $rc"; return 1
+  fi
+  if ! echo "$log_content" | grep -q "spawned scope=cloudflared-real-agent.scope"; then
+    echo "  scope unit name not derived correctly from .real-agent"
+    echo "$log_content"; return 1
+  fi
+  return 0
+}
+
+# CASE 5: --slice=cloudflared flag passed to systemd-run
+case_slice_flag_present() {
+  local root
+  root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "yes"
+
+  local log="$root/home/.maxy-code/logs/cloudflared.log"
+
+  HOME="$root/home" \
+  PATH="$root/bin:$PATH" \
+  MAXY_PLATFORM_ROOT="$root/platform_root" \
+    bash "$RESUME"
+
+  local log_content
+  log_content=$(cat "$log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  # The systemd-run stub echoes "[stub] slice=cloudflared" to stdout,
+  # which is redirected to LOG_FILE by the script's >> redirect.
+  if ! echo "$log_content" | grep -q "\[stub\] slice=cloudflared"; then
+    echo "  --slice=cloudflared not seen by systemd-run stub"
+    echo "$log_content"; return 1
+  fi
+  return 0
+}
+
+run_case "skip when scope active" case_skip_when_scope_active
+run_case "spawn succeeds and logs verified" case_spawn_succeeds
+run_case "spawn with no connection logs ERROR exits 0" case_spawn_no_connection
+run_case "scope unit name derived from configDir" case_scope_unit_name_from_config_dir
+run_case "slice flag passed to systemd-run" case_slice_flag_present
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]

package/payload/platform/scripts/resume-tunnel.sh

@@ -1,17 +1,18 @@
 #!/bin/bash
-# resume-tunnel.sh — Resume the Cloudflare tunnel on boot
+# resume-tunnel.sh — Resume the Cloudflare tunnel on brand-service start.
 #
-# Called as ExecStartPre in maxy.service. Reads brand-specific tunnel state
-# from ~/{configDir}/cloudflared/tunnel.state, checks whether the recorded
-# PID is still a running cloudflared process, and spawns a new daemon if not.
-# All failures exit 0 — this script must never prevent maxy.service from starting.
+# Spawns cloudflared into its own transient systemd scope (cloudflared-<brand>.scope)
+# under cloudflared.slice, completely decoupled from the brand service's cgroup.
+# A brand-service restart can no longer reap the tunnel. Task 602.
 #
-# Dependencies: jq, cloudflared (both installed by create-maxy)
+# Called as ExecStartPre in maxy.service. All failures exit 0 — this script must
+# never prevent maxy.service from starting.
+#
+# Dependencies: jq, cloudflared, systemd-run, systemctl
 
 set -uo pipefail
 
-# Derive configDir from brand.json (MAXY_PLATFORM_ROOT is set by the systemd service).
-# Fall back to .maxy if brand.json is unreadable.
+# Derive configDir from brand.json. Fall back to .maxy if unreadable.
 CONFIG_DIR=".maxy"
 if [ -n "${MAXY_PLATFORM_ROOT:-}" ] && [ -f "$MAXY_PLATFORM_ROOT/config/brand.json" ]; then
   BRAND_CONFIG_DIR=$(jq -r '.configDir // empty' "$MAXY_PLATFORM_ROOT/config/brand.json" 2>/dev/null || true)
@@ -20,9 +21,7 @@ if [ -n "${MAXY_PLATFORM_ROOT:-}" ] && [ -f "$MAXY_PLATFORM_ROOT/config/brand.js
   fi
 fi
 
-# State file under ~/{configDir}/cloudflared/ — each brand has its own tunnel state.
 STATE_FILE="$HOME/$CONFIG_DIR/cloudflared/tunnel.state"
-
 LOG_DIR="$HOME/$CONFIG_DIR/logs"
 LOG_FILE="$LOG_DIR/cloudflared.log"
 
@@ -32,13 +31,10 @@ log() {
 }
 
 # No state file — no tunnel configured. Normal boot.
-if [ ! -f "$STATE_FILE" ]; then
-  exit 0
-fi
+[ -f "$STATE_FILE" ] || exit 0
 
 log "reading state from $STATE_FILE (configDir=$CONFIG_DIR)"
 
-# Parse state file
 if ! STATE=$(jq -r '.' "$STATE_FILE" 2>/dev/null); then
   log "WARNING: tunnel.state is not valid JSON — skipping resume"
   exit 0
@@ -47,64 +43,106 @@ fi
 TUNNEL_ID=$(echo "$STATE" | jq -r '.tunnelId // empty')
 DOMAIN=$(echo "$STATE" | jq -r '.domain // empty')
 CONFIG_PATH=$(echo "$STATE" | jq -r '.configPath // empty')
-OLD_PID=$(echo "$STATE" | jq -r '.pid // empty')
 
 if [ -z "$TUNNEL_ID" ]; then
   log "WARNING: tunnel.state has no tunnelId — skipping resume"
   exit 0
 fi
 
-# Determine startup mode: config.yml (current) or --token (legacy)
-CERT_PATH="$HOME/$CONFIG_DIR/cloudflared/cert.pem"
+# Derive scope unit name: strip leading dot from CONFIG_DIR.
+# .maxy-code → cloudflared-maxy-code.scope
+BRAND="${CONFIG_DIR#.}"
+SCOPE_UNIT="cloudflared-${BRAND}.scope"
 
-# Check if the recorded PID is still a running cloudflared process
-if [ -n "$OLD_PID" ] && [ "$OLD_PID" != "null" ]; then
-  if kill -0 "$OLD_PID" 2>/dev/null; then
-    # PID is alive — verify it's actually cloudflared (not a reused PID)
-    PROC_NAME=$(cat "/proc/$OLD_PID/comm" 2>/dev/null || true)
-    if [ "$PROC_NAME" = "cloudflared" ]; then
-      log "Tunnel already running (PID $OLD_PID) — skipping resume"
-      exit 0
-    fi
-    # PID alive but not cloudflared — stale PID from before reboot
-    log "PID $OLD_PID is alive but is '$PROC_NAME', not cloudflared — will start new daemon"
-  fi
+# Liveness check: query the scope unit state, not a recorded PID.
+# The scope is owned by user-systemd, fully outside the brand service's cgroup.
+if systemctl --user is-active "$SCOPE_UNIT" >/dev/null 2>&1; then
+  SCOPE_PID=$(systemctl --user show "$SCOPE_UNIT" --property=MainPID --value 2>/dev/null || echo "unknown")
+  log "Tunnel already running (scope $SCOPE_UNIT active, MainPID $SCOPE_PID) — skipping resume"
+  exit 0
 fi
 
-# Find cloudflared binary
+CERT_PATH="$HOME/$CONFIG_DIR/cloudflared/cert.pem"
 CLOUDFLARED_BIN=$(command -v cloudflared 2>/dev/null || true)
+
 if [ -z "$CLOUDFLARED_BIN" ]; then
   log "ERROR: cloudflared binary not found — cannot resume tunnel"
   exit 0
 fi
 
-# Start the tunnel daemon (detached, survives service restart)
-log "Resuming tunnel $TUNNEL_ID for $DOMAIN..."
-mkdir -p "$LOG_DIR"
-
-if [ -n "$CONFIG_PATH" ] && [ -f "$CONFIG_PATH" ] && [ -f "$CERT_PATH" ]; then
-  log "Starting with config: $CONFIG_PATH, cert: $CERT_PATH"
-  nohup "$CLOUDFLARED_BIN" --origincert "$CERT_PATH" --config "$CONFIG_PATH" tunnel run >> "$LOG_FILE" 2>&1 &
-else
+if [ -z "$CONFIG_PATH" ] || [ ! -f "$CONFIG_PATH" ] || [ ! -f "$CERT_PATH" ]; then
   log "ERROR: missing configPath or cert — cannot resume tunnel"
   exit 0
 fi
-NEW_PID=$!
 
-if [ -z "$NEW_PID" ] || [ "$NEW_PID" -le 0 ] 2>/dev/null; then
-  log "ERROR: failed to spawn cloudflared — no PID returned"
-  exit 0
+log "Resuming tunnel $TUNNEL_ID for $DOMAIN..."
+
+# Capture log byte offset before spawning so the verification poll only
+# matches lines written by THIS invocation, not lines from a prior run.
+mkdir -p "$LOG_DIR"
+LOG_OFFSET=$(wc -c < "$LOG_FILE" 2>/dev/null | awk '{print $1+0}' || echo 0)
+
+# Spawn into a transient scope under cloudflared.slice.
+# The scope is owned by user-systemd, not by the brand service's cgroup.
+# systemd-run --scope blocks until cloudflared exits (it is the scope leader),
+# so we background it. $? after & is always 0 (fork success); the verification
+# gate below detects actual spawn failures via connection timeout.
+# stdout/stderr of cloudflared append to LOG_FILE via the redirect.
+systemd-run \
+  --user \
+  --scope \
+  --quiet \
+  --unit="$SCOPE_UNIT" \
+  --slice=cloudflared \
+  -p TimeoutStopSec=15 \
+  -- \
+  "$CLOUDFLARED_BIN" --origincert "$CERT_PATH" --config "$CONFIG_PATH" tunnel run \
+  >> "$LOG_FILE" 2>&1 &
+
+# Log spawn receipt so the operator can distinguish the scoped path from legacy nohup.
+SCOPE_PID=$(systemctl --user show "$SCOPE_UNIT" --property=MainPID --value 2>/dev/null || echo "unknown")
+log "spawned scope=$SCOPE_UNIT slice=cloudflared main-pid=$SCOPE_PID"
+
+# Post-spawn connection verification gate.
+# Polls only new log content (from LOG_OFFSET onwards) to avoid false positives
+# from "Registered tunnel connection" lines written by a prior run.
+# Overridable via RESUME_TUNNEL_VERIFY_DEADLINE for testing.
+# On failure: log explicit ERROR and exit 0 — must not block brand-service start.
+VERIFY_DEADLINE="${RESUME_TUNNEL_VERIFY_DEADLINE:-20}"
+VERIFY_START=$(date +%s)
+VERIFIED=0
+while true; do
+  if tail -c "+$((LOG_OFFSET + 1))" "$LOG_FILE" 2>/dev/null | grep -q "Registered tunnel connection"; then
+    VERIFIED=1
+    break
+  fi
+  NOW=$(date +%s)
+  ELAPSED=$(( NOW - VERIFY_START ))
+  if [ "$ELAPSED" -ge "$VERIFY_DEADLINE" ]; then
+    break
+  fi
+  sleep 1
+done
+
+if [ "$VERIFIED" -eq 1 ]; then
+  ELAPSED=$(( $(date +%s) - VERIFY_START ))
+  CONN_COUNT=$(tail -c "+$((LOG_OFFSET + 1))" "$LOG_FILE" 2>/dev/null | grep -c "Registered tunnel connection" || echo "?")
+  log "tunnel verified scope=$SCOPE_UNIT connections=$CONN_COUNT ms=$(( ELAPSED * 1000 ))"
+else
+  log "ERROR: tunnel scope started but no edge connection within ${VERIFY_DEADLINE}s — scope=$SCOPE_UNIT"
 fi
 
-# Update state file with new PID
-UPDATED_STATE=$(echo "$STATE" | jq --argjson pid "$NEW_PID" --argjson ts "$(date +%s)000" \
-  '.pid = $pid | .startedAt = $ts')
+# Update state file: keep pid/startedAt for observability, add scopeUnit as control signal.
+NEW_STATE=$(echo "$STATE" | jq \
+  --arg unit "$SCOPE_UNIT" \
+  --argjson ts "$(date +%s)000" \
+  '.scopeUnit = $unit | .startedAt = $ts' 2>/dev/null || echo "")
 
-if echo "$UPDATED_STATE" > "$STATE_FILE.tmp" 2>/dev/null && mv "$STATE_FILE.tmp" "$STATE_FILE" 2>/dev/null; then
-  log "Tunnel resumed — PID $NEW_PID"
+if [ -n "$NEW_STATE" ] && echo "$NEW_STATE" > "$STATE_FILE.tmp" 2>/dev/null && mv "$STATE_FILE.tmp" "$STATE_FILE" 2>/dev/null; then
+  :
 else
   rm -f "$STATE_FILE.tmp" 2>/dev/null
-  log "WARNING: tunnel started (PID $NEW_PID) but failed to update state file"
+  log "WARNING: tunnel started but failed to update state file"
 fi
 
 exit 0