@clawling/clawchat-plugin-openclaw 2026.7.6-3 → 2026.7.8-1

package/src/liveware-sample.ts

@@ -0,0 +1,625 @@
+/**
+ * Liveware Sample auto-boot: download the zero-dependency demo web app from the
+ * official install-cli repo (GitHub raw + manifest sha256, same channel as
+ * skill hot-update), run it locally, bind a liveware tunnel and register it as
+ * a ClawChat app — deterministically, without going through the LLM.
+ *
+ * Spec: docs/superpowers/specs/2026-07-06-liveware-sample-autoboot-design.md
+ */
+import crypto from "node:crypto";
+import { execFile as nodeExecFile, spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_SKILLS_REF, OFFICIAL_SKILLS_BASE, type FetchLike } from "./skill-update.ts";
+import type { LivewareSampleRow, LivewareSampleUpsert } from "./storage.ts";
+import type { LivewareLogger } from "./liveware-cli.ts";
+
+export const LIVEWARES_TARGET = "openclaw";
+export const LIVEWARE_SAMPLE_ID = "liveware-sample";
+export const LIVEWARE_SAMPLE_APP_NAME = "Liveware Sample";
+export const MAX_SAMPLE_FILE_BYTES = 512 * 1024;
+
+/** Files the agent owns at runtime; preserved across sample upgrades. */
+const USER_DATA_FILES = ["state.json", "events.jsonl"];
+
+export interface LivewareSampleManifestFile {
+  path: string;
+  sha256: string;
+  bytes: number;
+}
+
+export interface LivewareSampleManifestEntry {
+  version: string;
+  files: LivewareSampleManifestFile[];
+}
+
+function livewaresBase(base: string | undefined, ref: string): string {
+  return `${(base ?? OFFICIAL_SKILLS_BASE).replace(/\/+$/, "")}/${ref}/livewares`;
+}
+
+export function livewaresManifestUrl(ref: string = DEFAULT_SKILLS_REF, base?: string): string {
+  return `${livewaresBase(base, ref)}/manifest.json`;
+}
+
+export function livewareFileUrl(
+  filePath: string,
+  ref: string = DEFAULT_SKILLS_REF,
+  base?: string,
+): string {
+  return `${livewaresBase(base, ref)}/${filePath.replace(/^\/+/, "")}`;
+}
+
+export function parseLivewaresManifest(raw: string): LivewareSampleManifestEntry {
+  const parsed = JSON.parse(raw) as {
+    schema?: unknown;
+    livewares?: Record<string, Record<string, unknown>>;
+  };
+  const entry = parsed.livewares?.[LIVEWARES_TARGET]?.[LIVEWARE_SAMPLE_ID] as
+    | { version?: unknown; files?: unknown }
+    | undefined;
+  if (!entry) {
+    throw new Error(`livewares manifest missing ${LIVEWARES_TARGET}/${LIVEWARE_SAMPLE_ID}`);
+  }
+  const version = typeof entry.version === "string" ? entry.version.trim() : "";
+  if (!version) throw new Error("livewares manifest entry missing version");
+  if (!Array.isArray(entry.files) || entry.files.length === 0) {
+    throw new Error("livewares manifest entry missing files");
+  }
+  const files = entry.files.map((f, i) => {
+    const v = f as Record<string, unknown>;
+    const p = typeof v.path === "string" ? v.path.trim() : "";
+    const sha256 = typeof v.sha256 === "string" ? v.sha256.trim().toLowerCase() : "";
+    const bytes = typeof v.bytes === "number" ? v.bytes : NaN;
+    if (!p || p.includes("..")) throw new Error(`livewares manifest file[${i}] bad path`);
+    if (!/^[0-9a-f]{64}$/.test(sha256)) throw new Error(`livewares manifest file[${i}] bad sha256`);
+    if (!Number.isFinite(bytes) || bytes < 0 || bytes > MAX_SAMPLE_FILE_BYTES) {
+      throw new Error(`livewares manifest file[${i}] bad bytes`);
+    }
+    return { path: p, sha256, bytes };
+  });
+  return { version, files };
+}
+
+async function fetchText(fetchFn: FetchLike, url: string): Promise<string> {
+  const res = await fetchFn(url);
+  if (!res.ok) throw new Error(`fetch ${url} failed: HTTP ${res.status}`);
+  const text = await res.text();
+  if (Buffer.byteLength(text, "utf8") > MAX_SAMPLE_FILE_BYTES) {
+    throw new Error(`fetch ${url} exceeds ${MAX_SAMPLE_FILE_BYTES} bytes`);
+  }
+  return text;
+}
+
+/**
+ * Download + verify + atomically install the sample under `<sampleRoot>/app`.
+ * Preserves USER_DATA_FILES from an existing install. Throws on any failure;
+ * never leaves a partially-written `app/` dir behind.
+ */
+export async function downloadLivewareSample(opts: {
+  fetchFn: FetchLike;
+  sampleRoot: string;
+  ref?: string;
+  base?: string;
+}): Promise<{ version: string; appDir: string }> {
+  const ref = opts.ref ?? DEFAULT_SKILLS_REF;
+  const entry = parseLivewaresManifest(
+    await fetchText(opts.fetchFn, livewaresManifestUrl(ref, opts.base)),
+  );
+
+  const appDir = path.join(opts.sampleRoot, "app");
+  const tmpDir = path.join(opts.sampleRoot, `app.tmp-${process.pid}`);
+  await fs.promises.rm(tmpDir, { recursive: true, force: true });
+  await fs.promises.mkdir(tmpDir, { recursive: true });
+  try {
+    for (const file of entry.files) {
+      const text = await fetchText(opts.fetchFn, livewareFileUrl(file.path, ref, opts.base));
+      const buf = Buffer.from(text, "utf8");
+      const actual = crypto.createHash("sha256").update(buf).digest("hex");
+      if (actual !== file.sha256) {
+        throw new Error(`sha256 mismatch for ${file.path}: expected ${file.sha256} got ${actual}`);
+      }
+      await fs.promises.writeFile(path.join(tmpDir, path.basename(file.path)), buf);
+    }
+    // Preserve agent/user-owned data files from a previous install.
+    for (const name of USER_DATA_FILES) {
+      const prev = path.join(appDir, name);
+      if (fs.existsSync(prev)) {
+        await fs.promises.copyFile(prev, path.join(tmpDir, name));
+      }
+    }
+    await fs.promises.rm(appDir, { recursive: true, force: true });
+    await fs.promises.rename(tmpDir, appDir);
+    return { version: entry.version, appDir };
+  } catch (err) {
+    await fs.promises.rm(tmpDir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+export type SpawnLike = typeof nodeSpawn;
+export type ExecFileLike = typeof nodeExecFile;
+
+const SERVER_START_TIMEOUT_MS = 10_000;
+const TUNNEL_START_TIMEOUT_MS = 30_000;
+const CLI_TIMEOUT_MS = 30_000;
+
+/** Wait for a line matching `match` on the child's stdout/stderr, else kill+reject. */
+function waitForOutput(
+  child: ChildProcess,
+  match: (accumulated: string) => string | null,
+  timeoutMs: number,
+  label: string,
+): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    let acc = "";
+    let done = false;
+    const finish = (err: Error | null, value?: string) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      child.stdout?.removeListener("data", onData);
+      child.stderr?.removeListener("data", onData);
+      child.removeListener("exit", onExit);
+      if (err) {
+        try { child.kill("SIGTERM"); } catch { /* already dead */ }
+        reject(err);
+      } else {
+        resolve(value as string);
+      }
+    };
+    const timer = setTimeout(() => finish(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    const onData = (chunk: Buffer) => {
+      acc += chunk.toString();
+      const hit = match(acc);
+      if (hit != null) finish(null, hit);
+    };
+    const onExit = (code: number | null) => finish(new Error(`${label} exited early (code ${code})`));
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("exit", onExit);
+  });
+}
+
+export async function startSampleServer(opts: {
+  appDir: string;
+  port: number;
+  spawnFn?: SpawnLike;
+  timeoutMs?: number;
+}): Promise<{ child: ChildProcess; port: number }> {
+  const spawnFn = opts.spawnFn ?? nodeSpawn;
+  const child = spawnFn(
+    process.execPath,
+    [path.join(opts.appDir, "server.mjs"), "--dir", opts.appDir, "--port", String(opts.port)],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  const line = await waitForOutput(
+    child,
+    (acc) => acc.split("\n").find((l) => l.trim().startsWith('{"port"')) ?? null,
+    opts.timeoutMs ?? SERVER_START_TIMEOUT_MS,
+    "liveware-sample server start",
+  );
+  return { child, port: (JSON.parse(line) as { port: number }).port };
+}
+
+const URL_RE = /https?:\/\/[^\s"']+/g;
+
+/**
+ * Extract the public URL from `liveware tunnel bind` output. The real CLI prints
+ * an aligned table whose `domain` row carries the public host (no scheme), while
+ * the only literal URL in the output is the LOCAL `upstreamUrl` (http://127…).
+ * So prefer the `domain` field (→ `https://<domain>`); fall back to the first
+ * non-local http(s) URL for other output shapes. Returns null until a full
+ * `domain` line (trailing newline) has arrived, so streamed/partial chunks are
+ * never parsed into a truncated host.
+ */
+export function parseTunnelPublicUrl(output: string): string | null {
+  const text = output ?? "";
+  const dom = text.match(
+    /(?:^|\n)[ \t]*domain\b[ \t:=]+([A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9])[ \t]*\r?\n/i,
+  );
+  if (dom?.[1]) return `https://${dom[1]}`;
+  for (const u of text.match(URL_RE) ?? []) {
+    if (!/^https?:\/\/(127\.0\.0\.1|localhost|0\.0\.0\.0|\[::1\])(?:[:/]|$)/i.test(u)) return u;
+  }
+  return null;
+}
+
+export async function startTunnel(opts: {
+  livewarePath: string;
+  appId: string;
+  port: number;
+  spawnFn?: SpawnLike;
+  timeoutMs?: number;
+}): Promise<{ child: ChildProcess; publicUrl: string }> {
+  const spawnFn = opts.spawnFn ?? nodeSpawn;
+  const child = spawnFn(
+    opts.livewarePath,
+    ["tunnel", "bind", opts.appId, `http://127.0.0.1:${opts.port}`],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  const url = await waitForOutput(
+    child,
+    (acc) => parseTunnelPublicUrl(acc),
+    opts.timeoutMs ?? TUNNEL_START_TIMEOUT_MS,
+    "liveware tunnel bind",
+  );
+  return { child, publicUrl: url };
+}
+
+export async function livewareLogin(opts: {
+  livewarePath: string;
+  token: string;
+  execFileFn?: ExecFileLike;
+}): Promise<void> {
+  const execFileFn = opts.execFileFn ?? nodeExecFile;
+  await new Promise<void>((resolve, reject) => {
+    execFileFn(
+      opts.livewarePath,
+      ["login", "--access-token", opts.token],
+      { timeout: CLI_TIMEOUT_MS },
+      (err, stdout, stderr) => {
+        if (!err) { resolve(); return; }
+        const scrub = (s: string) => (opts.token ? String(s).split(opts.token).join("***") : String(s));
+        reject(new Error(`liveware login failed: ${scrub(stderr || stdout || String(err))}`.trim()));
+      },
+    );
+  });
+}
+
+/**
+ * Parse the app id out of `liveware app create` output. Tolerant of JSON or
+ * key/value text. Verified against the real CLI in the final manual task —
+ * adjust here if the real output shape differs.
+ */
+export function parseAppCreateOutput(stdout: string): string | null {
+  const text = (stdout ?? "").trim();
+  if (!text) return null;
+  // 1. JSON output: find the first string-valued id-like key, depth-first.
+  try {
+    const found = findIdDeep(JSON.parse(text));
+    if (found) return found;
+  } catch { /* not JSON */ }
+  // 2. Real `liveware app create` prints an aligned table row `appId   <id>`
+  //    (whitespace-separated, no colon); also tolerate `app id: xxx` / `AppID=xxx`.
+  const kv = text.match(/app[ _-]?id\b\s*[:=]?\s*"?([A-Za-z0-9][A-Za-z0-9_-]*)"?/i)
+    ?? text.match(/\bid\s*[:=]\s*"?([A-Za-z0-9][A-Za-z0-9_-]*)"?/i);
+  if (kv?.[1]) return kv[1];
+  // 3. A lone id-looking line (≥6 chars, single token).
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (/^[A-Za-z0-9][A-Za-z0-9_-]{5,}$/.test(t)) return t;
+  }
+  return null;
+}
+
+function findIdDeep(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const obj = value as Record<string, unknown>;
+  for (const key of ["app_id", "appId", "id"]) {
+    if (typeof obj[key] === "string" && (obj[key] as string).trim()) {
+      return (obj[key] as string).trim();
+    }
+  }
+  for (const v of Object.values(obj)) {
+    const found = findIdDeep(v);
+    if (found) return found;
+  }
+  return null;
+}
+
+export async function livewareAppCreate(opts: {
+  livewarePath: string;
+  name: string;
+  execFileFn?: ExecFileLike;
+}): Promise<string> {
+  const execFileFn = opts.execFileFn ?? nodeExecFile;
+  const stdout = await new Promise<string>((resolve, reject) => {
+    execFileFn(
+      opts.livewarePath,
+      ["app", "create", opts.name],
+      { timeout: CLI_TIMEOUT_MS },
+      (err, out, errOut) => {
+        if (err) { reject(new Error(`liveware app create failed: ${errOut || out || String(err)}`.trim())); return; }
+        resolve(String(out ?? ""));
+      },
+    );
+  });
+  const appId = parseAppCreateOutput(stdout);
+  if (!appId) throw new Error(`liveware app create: cannot parse app id from output: ${stdout.slice(0, 500)}`);
+  return appId;
+}
+
+export type LivewareSampleStoreLike = {
+  getLivewareSample(input: { platform: string; accountId: string }): LivewareSampleRow | null;
+  upsertLivewareSample(input: LivewareSampleUpsert): void;
+  updateLivewareSampleStatus(input: {
+    platform: string;
+    accountId: string;
+    status: "active" | "failed" | "disabled";
+    lastError?: string | null;
+  }): void;
+  markLivewareSampleIntroSent(input: { platform: string; accountId: string }): void;
+};
+
+export type LivewareSampleSupervisorDeps = {
+  platform: string;
+  accountId: string;
+  enabled: boolean;
+  store: LivewareSampleStoreLike;
+  sampleRoot: string;
+  resolveToken: () => string;
+  resolveLivewarePath: () => string | null;
+  /** Settles when the liveware CLI self-download has finished (either way).
+   * start() awaits it before the CLI gate so a first boot doesn't lose the
+   * race against ensureLivewareCli and silently skip forever. */
+  cliReady?: Promise<void>;
+  listApps: () => Promise<{ apps: { app_id?: string }[] }>;
+  registerApp: (p: { name: string; appId: string; url: string }) => Promise<unknown>;
+  notifyOwner: (text: string) => Promise<boolean>;
+  fetchFn: FetchLike;
+  ref?: string;
+  spawnFn?: SpawnLike;
+  execFileFn?: ExecFileLike;
+  log?: LivewareLogger;
+  setTimeoutFn?: typeof setTimeout;
+};
+
+export const LIVEWARE_SAMPLE_INTRO_TEXT =
+  "我给你安装了一个 liveware 演示应用「Liveware Sample」，它已经出现在我们的聊天里。" +
+  "点开它看看，然后试试对我说：把标题改成 Hello Liveware。" +
+  "你在页面上点的按钮、提交的留言我也能看到，随时问我。";
+
+const DEFAULT_SAMPLE_PORT = 43110;
+const RESTART_WINDOW_MS = 30 * 60 * 1000;
+const MAX_RESTARTS_PER_WINDOW = 5;
+const INTRO_RETRY_DELAY_MS = 30_000;
+const INTRO_MAX_TRIES = 20;
+
+export class LivewareSampleSupervisor {
+  private readonly deps: LivewareSampleSupervisorDeps;
+  private serverChild: ChildProcess | null = null;
+  private tunnelChild: ChildProcess | null = null;
+  private stopped = false;
+  private restartTimes: number[] = [];
+  private timers = new Set<ReturnType<typeof setTimeout>>();
+  /** Bumped on every (re)launch and on killChildren: a child's exit handler
+   * only counts if its generation is still current — killing the sibling
+   * child during a restart must NOT double-count as a second crash. */
+  private generation = 0;
+
+  constructor(deps: LivewareSampleSupervisorDeps) {
+    this.deps = deps;
+  }
+
+  /** Entry point. Never throws; every failure is logged + persisted only. */
+  async start(): Promise<void> {
+    const { deps } = this;
+    try {
+      if (!deps.enabled) return;
+      // ensureLivewareCli downloads the CLI asynchronously on first boot;
+      // gate the whole flow on it or resolveLivewarePath() below races to null.
+      if (deps.cliReady) await deps.cliReady;
+      if (this.stopped) return;
+      const key = { platform: deps.platform, accountId: deps.accountId };
+      const row = deps.store.getLivewareSample(key);
+      if (row?.status === "disabled") return;
+      if (row) {
+        await this.relaunch(row);
+      } else {
+        await this.bootstrap();
+      }
+    } catch (err) {
+      // A mid-flow failure (e.g. registerApp rejected) may have left children
+      // running without a persisted row — never leak orphan processes.
+      this.killChildren();
+      deps.log?.warn?.(`clawchat-plugin-openclaw liveware-sample start failed: ${String(err)}`);
+    }
+  }
+
+  stop(): void {
+    this.stopped = true;
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.killChildren();
+  }
+
+  private killChildren(): void {
+    this.generation += 1; // invalidate pending exit handlers before killing
+    for (const child of [this.serverChild, this.tunnelChild]) {
+      try { child?.kill("SIGTERM"); } catch { /* already dead */ }
+    }
+    this.serverChild = null;
+    this.tunnelChild = null;
+  }
+
+  private schedule(fn: () => void, delayMs: number): void {
+    if (this.stopped) return;
+    const setTimeoutFn = this.deps.setTimeoutFn ?? setTimeout;
+    const t = setTimeoutFn(() => { this.timers.delete(t); fn(); }, delayMs);
+    this.timers.add(t);
+  }
+
+  /** True (after killing any spawned children) when stop() arrived mid-flight.
+   * bootstrap()/relaunch() must re-check after every await: a child spawned
+   * after stop() ran would otherwise never be killed. */
+  private bailIfStopped(): boolean {
+    if (!this.stopped) return false;
+    this.killChildren();
+    return true;
+  }
+
+  private async bootstrap(): Promise<void> {
+    const { deps } = this;
+    if (this.stopped) return;
+    const livewarePath = deps.resolveLivewarePath();
+    if (!livewarePath) { deps.log?.warn?.("liveware-sample: liveware CLI not ready; skip"); return; }
+    const token = deps.resolveToken();
+    if (!token) { deps.log?.debug?.("liveware-sample: no token; skip"); return; }
+    let apps: { apps: { app_id?: string }[] };
+    try {
+      apps = await deps.listApps();
+    } catch (err) {
+      deps.log?.debug?.(`liveware-sample: listApps failed; skip bootstrap: ${String(err)}`);
+      return;
+    }
+    if (this.bailIfStopped()) return;
+    if (apps.apps.length > 0) {
+      deps.log?.debug?.("liveware-sample: user already has liveware apps; skip");
+      return;
+    }
+
+    const { version, appDir } = await downloadLivewareSample({
+      fetchFn: deps.fetchFn, sampleRoot: deps.sampleRoot, ref: deps.ref,
+    });
+    if (this.bailIfStopped()) return;
+    const server = await startSampleServer({
+      appDir, port: DEFAULT_SAMPLE_PORT, spawnFn: deps.spawnFn,
+    });
+    this.serverChild = server.child;
+    if (this.bailIfStopped()) return;
+    await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
+    const appId = await livewareAppCreate({
+      livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn,
+    });
+    const tunnel = await startTunnel({
+      livewarePath, appId, port: server.port, spawnFn: deps.spawnFn,
+    });
+    this.tunnelChild = tunnel.child;
+    if (this.bailIfStopped()) return;
+    await deps.registerApp({ name: LIVEWARE_SAMPLE_APP_NAME, appId, url: tunnel.publicUrl });
+    deps.store.upsertLivewareSample({
+      platform: deps.platform, accountId: deps.accountId,
+      appId, appName: LIVEWARE_SAMPLE_APP_NAME, port: server.port,
+      publicUrl: tunnel.publicUrl, sampleVersion: version, status: "active",
+    });
+    this.watchChildren();
+    await this.deliverIntro();
+    deps.log?.debug?.(`liveware-sample: bootstrap complete at ${tunnel.publicUrl}`);
+  }
+
+  private async relaunch(row: LivewareSampleRow): Promise<void> {
+    const { deps } = this;
+    if (this.stopped) return;
+    const livewarePath = deps.resolveLivewarePath();
+    if (!livewarePath) { deps.log?.warn?.("liveware-sample: liveware CLI not ready; skip relaunch"); return; }
+    // The user deleting the app tile is an explicit opt-out — never reinstall.
+    try {
+      const apps = await deps.listApps();
+      if (!apps.apps.some((a) => a.app_id === row.app_id)) {
+        deps.store.updateLivewareSampleStatus({
+          platform: deps.platform, accountId: deps.accountId, status: "disabled",
+          lastError: "app removed by user",
+        });
+        return;
+      }
+    } catch (err) {
+      deps.log?.debug?.(`liveware-sample: listApps failed; skip relaunch: ${String(err)}`);
+      return;
+    }
+    if (this.bailIfStopped()) return;
+
+    let version = row.sample_version;
+    let appDir = path.join(deps.sampleRoot, "app");
+    try {
+      const dl = await downloadLivewareSample({
+        fetchFn: deps.fetchFn, sampleRoot: deps.sampleRoot, ref: deps.ref,
+      });
+      version = dl.version;
+      appDir = dl.appDir;
+    } catch (err) {
+      if (!fs.existsSync(path.join(appDir, "server.mjs"))) throw err; // no local copy either — genuine failure
+      deps.log?.debug?.(`liveware-sample: download failed, reusing local copy: ${String(err)}`);
+    }
+    if (this.bailIfStopped()) return;
+    const server = await startSampleServer({
+      appDir, port: row.port || DEFAULT_SAMPLE_PORT, spawnFn: deps.spawnFn,
+    });
+    this.serverChild = server.child;
+    if (this.bailIfStopped()) return;
+    const tunnel = await startTunnel({
+      livewarePath, appId: row.app_id, port: server.port, spawnFn: deps.spawnFn,
+    });
+    this.tunnelChild = tunnel.child;
+    if (this.bailIfStopped()) return;
+    if (tunnel.publicUrl !== row.public_url) {
+      await deps.registerApp({
+        name: row.app_name, appId: row.app_id, url: tunnel.publicUrl,
+      });
+    }
+    deps.store.upsertLivewareSample({
+      platform: deps.platform, accountId: deps.accountId,
+      appId: row.app_id, appName: row.app_name, port: server.port,
+      publicUrl: tunnel.publicUrl, sampleVersion: version, status: "active",
+    });
+    this.watchChildren();
+    if (row.intro_sent === 0) await this.deliverIntro();
+  }
+
+  /** Restart (bounded backoff) when either child dies while we are not stopping. */
+  private watchChildren(): void {
+    const gen = ++this.generation;
+    const onChildExit = (): void => {
+      if (this.stopped || gen !== this.generation) return;
+      this.killChildren();
+      const now = Date.now();
+      this.restartTimes = this.restartTimes.filter((t) => now - t < RESTART_WINDOW_MS);
+      if (this.restartTimes.length >= MAX_RESTARTS_PER_WINDOW) {
+        this.deps.store.updateLivewareSampleStatus({
+          platform: this.deps.platform, accountId: this.deps.accountId,
+          status: "failed", lastError: "sample process crash-looping; restart cap reached",
+        });
+        this.deps.log?.warn?.("liveware-sample: restart cap reached; marked failed");
+        return;
+      }
+      const n = this.restartTimes.length;
+      this.restartTimes.push(now);
+      const delay = Math.min(5_000 * 2 ** n, 60_000);
+      this.schedule(() => {
+        const row = this.deps.store.getLivewareSample({
+          platform: this.deps.platform, accountId: this.deps.accountId,
+        });
+        if (!row || row.status === "disabled") return;
+        void this.relaunch(row).catch((err) => {
+          // A partially-completed relaunch may have spawned children before
+          // failing — never leave them running unwatched.
+          this.killChildren();
+          this.deps.log?.warn?.(`liveware-sample: relaunch failed: ${String(err)}`);
+          this.deps.store.updateLivewareSampleStatus({
+            platform: this.deps.platform, accountId: this.deps.accountId,
+            status: "failed", lastError: String(err),
+          });
+        });
+      }, delay);
+    };
+    for (const child of [this.serverChild, this.tunnelChild]) {
+      if (!child) continue;
+      child.once("exit", onChildExit);
+      // The child may have died during the awaits between spawn and here — its
+      // 'exit' event has already fired, so the once() above would never see it
+      // and the crash would be silently lost. Invoke the handler manually; the
+      // generation guard makes this idempotent with any late-arriving event.
+      if (child.exitCode != null || child.signalCode != null) onChildExit();
+    }
+  }
+
+  /** Deliver the intro chat message; retries while the WS client is not ready. */
+  private async deliverIntro(tryIndex = 0): Promise<void> {
+    if (this.stopped) return;
+    const { deps } = this;
+    let delivered = false;
+    try {
+      delivered = await deps.notifyOwner(LIVEWARE_SAMPLE_INTRO_TEXT);
+    } catch (err) {
+      deps.log?.debug?.(`liveware-sample: intro send error: ${String(err)}`);
+    }
+    if (delivered) {
+      deps.store.markLivewareSampleIntroSent({ platform: deps.platform, accountId: deps.accountId });
+      return;
+    }
+    if (tryIndex + 1 >= INTRO_MAX_TRIES) {
+      deps.log?.debug?.("liveware-sample: intro not delivered; will retry next boot");
+      return;
+    }
+    this.schedule(() => { void this.deliverIntro(tryIndex + 1); }, INTRO_RETRY_DELAY_MS);
+  }
+}