@rubytech/create-maxy-code 0.1.287 → 0.1.288

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

@@ -1,13 +1,14 @@
 // Task 602 — cloudflared.slice unit emitted at install time.
-// Every cloudflared-<brand>.scope spawned by resume-tunnel.sh drops under
+// Every cloudflared-<brand>.service spawned by resume-tunnel.sh drops under
 // this slice for cohort observability via `systemctl --user status cloudflared.slice`.
+// (Task 757 changed the per-brand unit from a scope to a supervised service.)
 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, /^Description=Cloudflare tunnel connectors \(Task 602\)$/m);
     assert.match(unit, /^\[Slice\]$/m);
     assert.match(unit, /^\[Install\]$/m);
     assert.match(unit, /^WantedBy=default\.target$/m);

package/dist/__tests__/cloudflared-version-pin.test.js

@@ -0,0 +1,24 @@
+// Task 757 — the cloudflared binary version is installer-owned and pinned.
+// The connector runs with --no-autoupdate (resume-tunnel.sh), so it never
+// self-replaces; the only way the binary version moves is bumping the pin in
+// installCloudflared and republishing the installer. This guards against a
+// regression back to the `releases/latest/download/` URL that let the binary
+// drift (the 2026-06-10 realagent-code outage root cause).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// The test runner compiles src -> dist and runs dist/__tests__/*.test.js, so
+// read the compiled sibling index.js; the URL string literal survives tsc.
+const here = dirname(fileURLToPath(import.meta.url));
+const compiled = readFileSync(join(here, "../index.js"), "utf8");
+test("cloudflared version is pinned to 2026.6.0", () => {
+    assert.match(compiled, /CLOUDFLARED_VERSION\s*=\s*"2026\.6\.0"/);
+});
+test("the .deb fetch URL is wired to the pinned version constant", () => {
+    assert.match(compiled, /releases\/download\/\$\{CLOUDFLARED_VERSION\}\/cloudflared-linux-/);
+});
+test("cloudflared .deb fetch no longer uses the drifting latest URL", () => {
+    assert.doesNotMatch(compiled, /releases\/latest\/download\/cloudflared-linux-/);
+});

package/dist/index.js

@@ -1599,6 +1599,13 @@ function installUv() {
         console.error("  WARNING: uv installed but uvx not on PATH — check $HOME/.local/bin");
     }
 }
+// Task 757 — cloudflared version is installer-owned and pinned. The connector
+// runs with --no-autoupdate (resume-tunnel.sh), so it never self-replaces; the
+// only way the binary version moves is bumping this pin and republishing the
+// installer. Fetching `latest` (the prior behaviour) let the binary drift at
+// install time and, combined with the connector's own auto-update, caused the
+// 2026-06-10 realagent-code tunnel outage.
+const CLOUDFLARED_VERSION = "2026.6.0";
 function installCloudflared() {
     if (commandExists("cloudflared")) {
         log("6", TOTAL, "Cloudflared already installed.");
@@ -1619,7 +1626,7 @@ function installCloudflared() {
     }
     const arch = isArm64() ? "arm64" : "amd64";
     const debPath = "/tmp/cloudflared.deb";
-    shellRetry("curl", ["-fSL", "--progress-bar", `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${arch}.deb`, "-o", debPath], { timeout: 120_000 }, 3, 10);
+    shellRetry("curl", ["-fSL", "--progress-bar", `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-${arch}.deb`, "-o", debPath], { timeout: 120_000 }, 3, 10);
     console.log("  [privileged] dpkg -i");
     shell("dpkg", ["-i", debPath], { sudo: true });
     spawnSync("rm", ["-f", debPath]);
@@ -3180,11 +3187,12 @@ function installService() {
     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.
+    // cloudflared-<brand>.service spawned by resume-tunnel.sh drops under this
+    // slice (Task 757 changed the unit from a scope to a supervised service).
+    // 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`);
+    logFile(`  ${cloudflaredSliceName}: Task 602 slice for cloudflared-*.service 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

@@ -187,16 +187,17 @@ WantedBy=default.target
 `;
 }
 // ---------------------------------------------------------------------------
-// Task 602 — `cloudflared.slice` unit. Every cloudflared-<brand>.scope
+// Task 602 — `cloudflared.slice` unit. Every cloudflared-<brand>.service
 // spawned by resume-tunnel.sh drops under this slice for one-glance cohort
-// observability (`systemctl --user status cloudflared.slice`).
+// observability (`systemctl --user status cloudflared.slice`). Task 757
+// changed the per-brand unit from a transient scope to a supervised service.
 //
 // 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)
+Description=Cloudflare tunnel connectors (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
 

package/dist/uninstall.js

@@ -181,24 +181,25 @@ function stopServices() {
     catch {
         console.log(`  ${neo4jService} 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".
+    // Stop the cloudflared service for this brand (Task 757 — the connector now
+    // runs as a supervised cloudflared-<brand>.service, not a transient scope).
+    // The 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.
+    // Exit 5 (no such unit) = service absent = success.
     const brand = BRAND.configDir.replace(/^\./, "");
-    const scopeUnit = `cloudflared-${brand}.scope`;
-    const stopResult = spawnSync("systemctl", ["--user", "stop", "--no-block", scopeUnit], { stdio: "pipe" });
+    const serviceUnit = `cloudflared-${brand}.service`;
+    const stopResult = spawnSync("systemctl", ["--user", "stop", "--no-block", serviceUnit], { stdio: "pipe" });
     if (stopResult.status === 0) {
-        console.log(`  Stopped ${scopeUnit}`);
+        console.log(`  Stopped ${serviceUnit}`);
     }
     else if (stopResult.status === 5) {
-        // exit 5 = unit not found — scope already absent, which is expected
-        console.log(`  ${scopeUnit} not running (scope absent)`);
+        // exit 5 = unit not found — service already absent, which is expected
+        console.log(`  ${serviceUnit} not running (service 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`);
+        console.log(`  systemctl stop ${serviceUnit} exited ${stopResult.status} — service 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.287",
+  "version": "0.1.288",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/business-assistant/skills/e-sign/SKILL.md

@@ -422,7 +422,7 @@ Before persisting, **read every rendered page** of `base.pdf` — full-bleed pag
 
 ## 6. Sweep + dispatch
 
-When the durable routine (§ 8.2) runs, or when the operator asks for new acceptances. Mint one **D1-Edit** token here — `${MINTED_D1_EDIT}` — per `api.md` § Minting a narrow token, resolving the permission-group id as `d1-data-capture.md` § 0 does. Reads use the Edit token too: the D1 **query** endpoint rejects a D1-Read token (`d1-data-capture.md`), so a separate read-scoped token is not minted.
+Dispatch runs **only** inside a live operator session on the account's own device — when the operator asks for new acceptances, or when an in-session watcher running inside a still-live session performs the sweep. There is no off-device dispatcher; never register a Claude Code `/schedule` routine or any headless/cloud scheduler to run it (§ 8.2 says why). Mint one **D1-Edit** token here — `${MINTED_D1_EDIT}` — per `api.md` § Minting a narrow token, resolving the permission-group id as `d1-data-capture.md` § 0 does. Reads use the Edit token too: the D1 **query** endpoint rejects a D1-Read token (`d1-data-capture.md`), so a separate read-scoped token is not minted.
 
 1. **Read the unswept rows** with `${MINTED_D1_EDIT}`:
 
@@ -530,16 +530,20 @@ The flow has no application logging — the signal surface is the **D1 row state
 
 Signal fires *without reproducing end to end*: the test POST returns non-`ok`, and the confirming `SELECT WHERE swept = 0` shows no new row. Fix: re-mint the token confirming **both** Pages Edit and D1 Edit (`d1-data-capture.md` § 0). First thing to check when acceptances stop arriving.
 
-### 8.2 Acceptance recorded but never dispatched (no-event) — the durable health check
+### 8.2 Acceptance recorded but never dispatched (no-event) — the in-session reconciliation check
 
-The sweep never ran, or `email-send` failed after the row existed — no log, because no action was taken. The sweep (§ 6) runs from a **durable platform routine**, not a session-only cron: a session cron dies with the session and produces no signal, so aged acceptances would sit undispatched silently. The routine's **health check** is the standing reconciliation:
+The sweep never ran, or `email-send` failed after the row existed — no log, because no action was taken. **Capture is durable; dispatch is not.** The acceptance is recorded at the **edge** in D1 (intro / § 1a) the instant the signer submits — nothing is ever lost, whether or not a session is running. **Dispatch** (stamp + email) needs the account's Pi-local tooling — the D1-Edit token, `email-send`, `stamp.mjs`, `ACCOUNT_DIR` — so it happens **only** while an operator session is live. An acceptance captured while no session is running sits **unswept** until the next session runs the sweep; latency is bounded by operator session cadence, not a cron. That is a deliberate limitation of the in-session-only model, not a defect — the durable D1 row guarantees no loss. The standing check is the operator's **session-open / before-close ritual**: run the reconciliation inside a live session, and any aged unswept row is the signal to sweep now.
+
+> Dispatch runs **only** inside a live operator session on the account's own device. Never register a Claude Code `/schedule` routine, a `RemoteTrigger`, a `CronCreate` durable job, or any off-device/headless scheduler to run the sweep. `/schedule` spawns a fresh agent on **claude.ai's cloud**, which has none of this account's D1 token, `email-send`, `stamp.mjs`, or `ACCOUNT_DIR` — it physically cannot stamp or send. It is a Claude Code capability, not a Maxy one, and it is not a substitute for the in-session sweep. Monitoring and dispatch happen in-session, while the session is live. That is the only path.
+
+The reconciliation query, run inside a live session at open and before close:
 
 ```bash
 CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" wrangler d1 execute <db-name> --remote --command \
   "SELECT count(*), min(accepted_at) FROM acceptances WHERE swept = 0;"
 ```
 
-Any row whose `accepted_at` is older than the routine's cadence is an undispatched acceptance — the failure signal. Because § 6 flips `swept` only after both sends verify (and a text-only degrade is treated as a failed send, § 0 item 3), a failed or degraded dispatch leaves the row here for the next pass.
+Any row whose `accepted_at` is older than the operator's session cadence is an undispatched acceptance — the failure signal. Because § 6 flips `swept` only after both sends verify (and a text-only degrade is treated as a failed send, § 0 item 3), a failed or degraded dispatch leaves the row here for the next pass.
 
 ### 8.3 Document modified after an acceptance, or base render missing (signed-content drift)
 

package/payload/platform/plugins/cloudflare/references/manual-setup.md

@@ -226,6 +226,7 @@ Only if that line prints nothing (all vars set) do you proceed to write the conf
 cat > "${CFG_DIR}/config.yml" <<EOF
 tunnel: ${TUNNEL_ID}
 credentials-file: ${CFG_DIR}/${TUNNEL_ID}.json
+no-autoupdate: true
 ingress:
   - hostname: admin.maxy.bot
     service: http://localhost:${PORT}
@@ -235,7 +236,7 @@ ingress:
 EOF
 ```
 
-**Why:** Tells cloudflared at startup which tunnel to run, where its credentials are, and how to route each hostname to the brand's local service port. The trailing `http_status:404` line is the mandatory catch-all.
+**Why:** Tells cloudflared at startup which tunnel to run, where its credentials are, and how to route each hostname to the brand's local service port. The trailing `http_status:404` line is the mandatory catch-all. `no-autoupdate: true` stops the connector downloading a new binary and replacing itself (which exits the running process); the cloudflared version is installer-owned and bumped deliberately. This is belt-and-braces with the `--no-autoupdate` flag `resume-tunnel.sh` already passes on the spawn argv — the flag covers every existing install on its next service restart, this line covers a connector started any other way from a freshly-provisioned config. Task 757.
 
 **Success:** Confirm with:
 
@@ -425,7 +426,22 @@ A non-530 response means the tunnel is live.
 
 **Do NOT use `sudo cloudflared service install`.** It writes `/etc/systemd/system/cloudflared.service`, copies your config to `/etc/cloudflared/config.yml` (a system-wide path), and runs the connector as root — breaking brand isolation on any device that hosts more than one brand under the same Linux user. We tried this path on 2026-04-19; it created a duplicate connector parallel to the existing user-space one and required an explicit uninstall to undo.
 
-The correct production pattern is already in place on every Maxy device: the brand's platform UI itself is a **user-space systemd service** at `~/.config/systemd/user/<brand>.service`, and that service spawns the cloudflared connector as an `ExecStartPre=` via `platform/scripts/resume-tunnel.sh`. When the user-space service restarts, the connector restarts with it. The connector runs as the Linux user (not root), its config is read from `${CFG_DIR}/config.yml` (brand-scoped, never `/etc`), and multiple brands coexist because each has its own unit file (`maxy.service`, `realagent.service`, etc.).
+The correct production pattern is already in place on every Maxy device: the brand's platform UI itself is a **user-space systemd service** at `~/.config/systemd/user/<brand>.service`, and that service spawns the cloudflared connector as an `ExecStartPre=` via `platform/scripts/resume-tunnel.sh`. The connector runs as the Linux user (not root), its config is read from `${CFG_DIR}/config.yml` (brand-scoped, never `/etc`), and multiple brands coexist because each has its own unit file (`maxy.service`, `realagent.service`, etc.).
+
+**The connector is a supervised, self-healing unit (Task 602 + Task 757).** `resume-tunnel.sh` does not run cloudflared as a child of the brand service. It spawns it into its own transient systemd **service** — `cloudflared-<brand>.service` under `cloudflared.slice` — with `Restart=always`. Two consequences: a brand-service restart no longer reaps the connector (Task 602's cgroup decoupling), and systemd resurrects the connector on **any** exit — crash, OOM, manual kill (Task 757). The connector also runs with `--no-autoupdate`, so it never downloads a new binary and replaces itself; the version is installer-owned (pinned in the installer, bumped deliberately). `StartLimitIntervalSec=300`/`StartLimitBurst=5` mean a genuinely broken binary surfaces as a `failed` unit instead of looping forever.
+
+**Observability.** A connector death is now a logged, countable event, not an invisible gap:
+
+```
+# Every restart systemd performs is journaled for the connector's own unit:
+journalctl --user -u cloudflared-<brand>.service | grep "Scheduled restart job"
+# (each line: "Scheduled restart job, restart counter is at N")
+
+# Confirm auto-update is off — cloudflared prints its effective settings at startup:
+grep "no-autoupdate:true" "${CFG_DIR}/logs/cloudflared.log"
+```
+
+`no-autoupdate:true` in cloudflared's startup `Settings:` line is the per-box rollout acceptance signal. A unit that has tripped its start limit shows `Active: failed` under `systemctl --user status cloudflared-<brand>.service` — investigate the binary rather than restarting blindly.
 
 **Durability prerequisites (one-time per device):**
 

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

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
-# Tests for resume-tunnel.sh scope-based spawn path (Task 602).
+# Tests for resume-tunnel.sh supervised-service spawn path (Task 602 + Task 757).
+# Task 602 decoupled the connector into its own transient unit under
+# cloudflared.slice; Task 757 changed that unit from a --scope (no restart
+# policy) to a --service with Restart=always and --no-autoupdate.
 # Stubs systemd-run, systemctl, and cloudflared binaries via a fake $PATH entry.
 set -uo pipefail
 
@@ -80,10 +83,12 @@ exit 0
 SH
   chmod +x "$bin_dir/systemctl"
 
-  # Stub systemd-run: logs its --unit= and --slice= args, optionally writes connection line.
+  # Stub systemd-run: echoes every arg (so tests can assert the unit name, slice,
+  # restart properties, and the connector argv), optionally writes connection line.
   cat > "$bin_dir/systemd-run" <<SH
 #!/bin/bash
 for arg in "\$@"; do
+  echo "[stub] arg=\$arg"
   case "\$arg" in
     --unit=*) echo "[stub] unit=\${arg#--unit=}" ;;
     --slice=*) echo "[stub] slice=\${arg#--slice=}" ;;
@@ -120,7 +125,7 @@ case_skip_when_scope_active() {
   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
+  if ! echo "$log_content" | grep -q "already running.*service.*cloudflared-maxy-code.service"; then
     echo "  skip branch missing expected log line"
     echo "$log_content"
     return 1
@@ -149,8 +154,8 @@ case_spawn_succeeds() {
   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
+  if ! echo "$log_content" | grep -q "spawned service=cloudflared-maxy-code.service"; then
+    echo "  missing spawned service 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
@@ -186,7 +191,7 @@ case_spawn_no_connection() {
   return 0
 }
 
-# CASE 4: scope unit name derived correctly from configDir (.real-agent → cloudflared-real-agent.scope)
+# CASE 4: service unit name derived correctly from configDir (.real-agent → cloudflared-real-agent.service)
 case_scope_unit_name_from_config_dir() {
   local root
   root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
@@ -207,8 +212,8 @@ case_scope_unit_name_from_config_dir() {
   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"
+  if ! echo "$log_content" | grep -q "spawned service=cloudflared-real-agent.service"; then
+    echo "  service unit name not derived correctly from .real-agent"
     echo "$log_content"; return 1
   fi
   return 0
@@ -240,11 +245,43 @@ case_slice_flag_present() {
   return 0
 }
 
-run_case "skip when scope active" case_skip_when_scope_active
+# CASE 6: supervision contract — Restart=always, crash-loop limits, --no-autoupdate,
+# and the unit is a .service (Task 757), all reaching systemd-run.
+case_supervision_contract() {
+  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"
+
+  local missing=""
+  echo "$log_content" | grep -q "\[stub\] arg=--unit=cloudflared-maxy-code.service" || missing="$missing unit=.service"
+  echo "$log_content" | grep -q "\[stub\] arg=Restart=always" || missing="$missing Restart=always"
+  echo "$log_content" | grep -q "\[stub\] arg=StartLimitIntervalSec=300" || missing="$missing StartLimitIntervalSec"
+  echo "$log_content" | grep -q "\[stub\] arg=StartLimitBurst=5" || missing="$missing StartLimitBurst"
+  echo "$log_content" | grep -q "\[stub\] arg=--no-autoupdate" || missing="$missing --no-autoupdate"
+  if [[ -n "$missing" ]]; then
+    echo "  systemd-run argv missing:$missing"
+    echo "$log_content"; return 1
+  fi
+  return 0
+}
+
+run_case "skip when service 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 "service unit name derived from configDir" case_scope_unit_name_from_config_dir
 run_case "slice flag passed to systemd-run" case_slice_flag_present
+run_case "supervision contract: restart-always + no-autoupdate + .service" case_supervision_contract
 
 echo ""
 echo "Results: $PASS passed, $FAIL failed"

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

@@ -1,9 +1,15 @@
 #!/bin/bash
 # resume-tunnel.sh — Resume the Cloudflare tunnel on brand-service start.
 #
-# Spawns cloudflared into its own transient systemd scope (cloudflared-<brand>.scope)
+# Spawns cloudflared into its own transient systemd SERVICE (cloudflared-<brand>.service)
 # under cloudflared.slice, completely decoupled from the brand service's cgroup.
-# A brand-service restart can no longer reap the tunnel. Task 602.
+# A brand-service restart can no longer reap the tunnel (Task 602's cgroup
+# decoupling). The unit is a Restart=always service (Task 757), so systemd
+# resurrects the connector on ANY exit — crash, OOM, manual kill — and the
+# connector runs with --no-autoupdate so it never replaces itself; the binary
+# version is installer-owned. This is still the single spawner: only the unit
+# type changed from a transient --scope (no restart policy) to a supervised
+# --service. No second spawner is introduced.
 #
 # Called as ExecStartPre in maxy.service. All failures exit 0 — this script must
 # never prevent maxy.service from starting.
@@ -49,16 +55,16 @@ if [ -z "$TUNNEL_ID" ]; then
   exit 0
 fi
 
-# Derive scope unit name: strip leading dot from CONFIG_DIR.
-# .maxy-code → cloudflared-maxy-code.scope
+# Derive service unit name: strip leading dot from CONFIG_DIR.
+# .maxy-code → cloudflared-maxy-code.service
 BRAND="${CONFIG_DIR#.}"
-SCOPE_UNIT="cloudflared-${BRAND}.scope"
+SERVICE_UNIT="cloudflared-${BRAND}.service"
 
-# 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"
+# Liveness check: query the service unit state, not a recorded PID.
+# The service is owned by user-systemd, fully outside the brand service's cgroup.
+if systemctl --user is-active "$SERVICE_UNIT" >/dev/null 2>&1; then
+  SERVICE_PID=$(systemctl --user show "$SERVICE_UNIT" --property=MainPID --value 2>/dev/null || echo "unknown")
+  log "Tunnel already running (service $SERVICE_UNIT active, MainPID $SERVICE_PID) — skipping resume"
   exit 0
 fi
 
@@ -82,26 +88,37 @@ log "Resuming tunnel $TUNNEL_ID for $DOMAIN..."
 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.
+# Spawn into a SUPERVISED transient service under cloudflared.slice (Task 757).
+# Unlike a --scope (no restart policy), a Restart=always service is resurrected
+# by systemd on ANY exit — crash, OOM, manual kill. --no-autoupdate stops the
+# connector replacing its own binary, so the version stays installer-owned.
+# StartLimitIntervalSec/StartLimitBurst trip a genuinely broken binary to
+# `failed` instead of looping forever (5 starts within 300s → failed).
+# A service's stdout/stderr go to the journal, not this shell, so route them to
+# LOG_FILE via StandardOutput/StandardError=append so the verification gate
+# below and the operator's cloudflared.log keep working. systemd-run returns
+# once the unit is active (it does not block for the process lifetime), so there
+# is no shell child to background. --quiet suppresses systemd-run's "Running as
+# unit:" line; the trailing redirect only captures any error output it prints.
 systemd-run \
   --user \
-  --scope \
   --quiet \
-  --unit="$SCOPE_UNIT" \
+  --unit="$SERVICE_UNIT" \
   --slice=cloudflared \
+  -p Restart=always \
+  -p RestartSec=2 \
+  -p StartLimitIntervalSec=300 \
+  -p StartLimitBurst=5 \
   -p TimeoutStopSec=15 \
+  -p "StandardOutput=append:$LOG_FILE" \
+  -p "StandardError=append:$LOG_FILE" \
   -- \
-  "$CLOUDFLARED_BIN" --origincert "$CERT_PATH" --config "$CONFIG_PATH" tunnel run \
-  >> "$LOG_FILE" 2>&1 &
+  "$CLOUDFLARED_BIN" --no-autoupdate --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"
+# Log spawn receipt so the operator can distinguish the supervised path from legacy nohup.
+SERVICE_PID=$(systemctl --user show "$SERVICE_UNIT" --property=MainPID --value 2>/dev/null || echo "unknown")
+log "spawned service=$SERVICE_UNIT slice=cloudflared main-pid=$SERVICE_PID"
 
 # Post-spawn connection verification gate.
 # Polls only new log content (from LOG_OFFSET onwards) to avoid false positives
@@ -127,16 +144,16 @@ 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 ))"
+  log "tunnel verified service=$SERVICE_UNIT connections=$CONN_COUNT ms=$(( ELAPSED * 1000 ))"
 else
-  log "ERROR: tunnel scope started but no edge connection within ${VERIFY_DEADLINE}s — scope=$SCOPE_UNIT"
+  log "ERROR: tunnel service started but no edge connection within ${VERIFY_DEADLINE}s — service=$SERVICE_UNIT"
 fi
 
-# Update state file: keep pid/startedAt for observability, add scopeUnit as control signal.
+# Update state file: keep pid/startedAt for observability, add serviceUnit as control signal.
 NEW_STATE=$(echo "$STATE" | jq \
-  --arg unit "$SCOPE_UNIT" \
+  --arg unit "$SERVICE_UNIT" \
   --argjson ts "$(date +%s)000" \
-  '.scopeUnit = $unit | .startedAt = $ts' 2>/dev/null || echo "")
+  '.serviceUnit = $unit | .startedAt = $ts' 2>/dev/null || echo "")
 
 if [ -n "$NEW_STATE" ] && echo "$NEW_STATE" > "$STATE_FILE.tmp" 2>/dev/null && mv "$STATE_FILE.tmp" "$STATE_FILE" 2>/dev/null; then
   :