@clawling/clawchat-plugin-openclaw 2026.7.29-3 → 2026.8.4-1

package/src/liveware-sample.ts

@@ -20,6 +20,36 @@ 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"];
 
+/**
+ * Windows refuses to unlink or rename a directory while ANY file inside it is
+ * still open, and reports it as a sharing violation (EPERM/EBUSY/EACCES) or a
+ * non-empty directory. A still-draining sample server, an antivirus scan or the
+ * search indexer is enough to trigger it, and all of those clear within
+ * milliseconds — so a short bounded retry turns a hard install failure into a
+ * brief pause. On POSIX these codes essentially never appear here and the first
+ * attempt always wins, so the retry costs nothing.
+ */
+const FS_SWAP_RETRY_DELAYS_MS = [50, 150, 400];
+const TRANSIENT_FS_CODES = new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY"]);
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function withFsSwapRetry<T>(op: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= FS_SWAP_RETRY_DELAYS_MS.length; attempt += 1) {
+    try {
+      return await op();
+    } catch (err) {
+      lastError = err;
+      const code = (err as NodeJS.ErrnoException).code ?? "";
+      const delay = FS_SWAP_RETRY_DELAYS_MS[attempt];
+      if (!TRANSIENT_FS_CODES.has(code) || delay === undefined) break;
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
 export interface LivewareSampleManifestFile {
   path: string;
   sha256: string;
@@ -88,28 +118,85 @@ async function fetchText(fetchFn: FetchLike, url: string): Promise<string> {
   return text;
 }
 
+/**
+ * True when `appDir` already holds what the manifest pins: every listed file
+ * present, program files byte-identical to their manifest sha256, and nothing
+ * beyond those files (so a file dropped by a newer manifest still forces a clean
+ * reinstall). USER_DATA_FILES are checked for presence only, never for content —
+ * `state.json` ships in the manifest *and* is owned by the agent afterwards, so
+ * hashing it would make the short-circuit miss on exactly the installs that are
+ * actually in use. Cheap (~20 KB of local reads) next to the per-file GETs it
+ * saves, and fail-safe: any read error answers "no".
+ */
+async function localInstallMatches(
+  appDir: string,
+  entry: LivewareSampleManifestEntry,
+): Promise<boolean> {
+  try {
+    const expected = new Set(entry.files.map((f) => path.basename(f.path)));
+    for (const name of await fs.promises.readdir(appDir)) {
+      if (!expected.has(name) && !USER_DATA_FILES.includes(name)) return false;
+    }
+    for (const file of entry.files) {
+      const name = path.basename(file.path);
+      const target = path.join(appDir, name);
+      if (USER_DATA_FILES.includes(name)) {
+        await fs.promises.access(target); // agent-owned: presence is the whole check
+        continue;
+      }
+      const buf = await fs.promises.readFile(target);
+      if (crypto.createHash("sha256").update(buf).digest("hex") !== file.sha256) return false;
+    }
+    return true;
+  } catch {
+    return false; // missing / unreadable — treat as "not installed"
+  }
+}
+
 /**
  * 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.
+ *
+ * Re-install short-circuit: when the installed bytes already match every hash
+ * the manifest pins, nothing is fetched or rewritten (`reused: true`). Every
+ * boot used to re-fetch the whole bundle from GitHub raw even when the identical
+ * files were already on disk — a handful of serial round-trips on the critical
+ * path, and an unreachable raw.githubusercontent then failed a sample that was
+ * already fully installed. Only the manifest itself is still fetched every time,
+ * because that is what tells us which hashes to compare against.
  */
 export async function downloadLivewareSample(opts: {
   fetchFn: FetchLike;
   sampleRoot: string;
   ref?: string;
   base?: string;
-}): Promise<{ version: string; appDir: string }> {
+}): Promise<{ version: string; appDir: string; reused?: boolean }> {
   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");
+  if (await localInstallMatches(appDir, entry)) {
+    return { version: entry.version, appDir, reused: true };
+  }
+  // Sweep app.old-* left behind when a previous swap could not delete the old
+  // tree (a handle was still open then, but is not now). Best effort: a dir we
+  // still cannot remove is simply retried next run.
+  for (const name of await fs.promises.readdir(opts.sampleRoot).catch(() => [])) {
+    if (name.startsWith("app.old-")) {
+      await fs.promises.rm(path.join(opts.sampleRoot, name), { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
   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) {
+    // Fetched concurrently: the files are independent and each is a separate
+    // round-trip to the same host, so serializing them only added latency.
+    await Promise.all(entry.files.map(async (file) => {
       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");
@@ -117,7 +204,7 @@ export async function downloadLivewareSample(opts: {
         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);
@@ -125,8 +212,18 @@ export async function downloadLivewareSample(opts: {
         await fs.promises.copyFile(prev, path.join(tmpDir, name));
       }
     }
-    await fs.promises.rm(appDir, { recursive: true, force: true });
-    await fs.promises.rename(tmpDir, appDir);
+    // Swap by moving the old tree ASIDE rather than deleting it first. On
+    // Windows the delete is the step most likely to lose a race with an open
+    // handle, and doing it first leaves no app/ at all when it fails. Renaming
+    // aside puts the new tree in place first and makes the delete best-effort:
+    // a leftover app.old-<pid> is swept on the next run, never a broken install.
+    const oldDir = path.join(opts.sampleRoot, `app.old-${process.pid}`);
+    await fs.promises.rm(oldDir, { recursive: true, force: true }).catch(() => {});
+    if (fs.existsSync(appDir)) {
+      await withFsSwapRetry(() => fs.promises.rename(appDir, oldDir));
+    }
+    await withFsSwapRetry(() => fs.promises.rename(tmpDir, appDir));
+    await fs.promises.rm(oldDir, { recursive: true, force: true }).catch(() => {});
     return { version: entry.version, appDir };
   } catch (err) {
     await fs.promises.rm(tmpDir, { recursive: true, force: true });
@@ -137,6 +234,34 @@ export async function downloadLivewareSample(opts: {
 export type SpawnLike = typeof nodeSpawn;
 export type ExecFileLike = typeof nodeExecFile;
 
+/**
+ * Terminate a child and everything it spawned.
+ *
+ * POSIX: `SIGTERM` to the child is what we want and what the child expects.
+ *
+ * Windows: there are no signals. `child.kill()` maps to TerminateProcess on
+ * that one process, so any grandchild the liveware agent spawned survives —
+ * orphaned, still holding the sample port, and invisible to the next boot,
+ * which then fails to bind. `taskkill /T /F` takes the whole tree down.
+ * Fire-and-forget: we never wait on it, and a failure (already dead, no such
+ * pid) falls through to the ordinary kill().
+ */
+export function killProcessTree(
+  child: ChildProcess | null | undefined,
+  execFileFn: ExecFileLike = nodeExecFile,
+): void {
+  if (!child) return;
+  if (process.platform === "win32" && typeof child.pid === "number") {
+    try {
+      execFileFn("taskkill", ["/pid", String(child.pid), "/T", "/F"], () => {});
+      return;
+    } catch {
+      // taskkill missing or spawn refused — fall back to the plain kill below.
+    }
+  }
+  try { child.kill("SIGTERM"); } catch { /* already dead */ }
+}
+
 const SERVER_START_TIMEOUT_MS = 10_000;
 const TUNNEL_START_TIMEOUT_MS = 30_000;
 const CLI_TIMEOUT_MS = 30_000;
@@ -159,7 +284,7 @@ function waitForOutput(
       child.stderr?.removeListener("data", onData);
       child.removeListener("exit", onExit);
       if (err) {
-        try { child.kill("SIGTERM"); } catch { /* already dead */ }
+        killProcessTree(child);
         reject(err);
       } else {
         resolve(value as string);
@@ -351,6 +476,96 @@ function findIdDeep(value: unknown): string | null {
   return null;
 }
 
+/**
+ * Find the id of an existing liveware app named `name` in `liveware app list`
+ * output. Deliberately conservative: a shape this cannot read must degrade to
+ * "not found" — the caller then creates an app, i.e. the previous behaviour —
+ * and must never return a WRONG id, so the text branch only accepts a line that
+ * contains the exact app name plus one id-looking token outside it, and an
+ * id-looking token must carry a digit/`-`/`_` so a status word ("active",
+ * "running") cannot pass for an id. JSON output (any wrapper key) is the
+ * reliable path; the aligned-table branch is calibrated on `app create`'s table,
+ * the only text shape verified against the real CLI.
+ */
+export function findAppIdByName(stdout: string, name: string): string | null {
+  const text = (stdout ?? "").trim();
+  const wanted = (name ?? "").trim();
+  if (!text || !wanted) return null;
+  try {
+    const found = findNamedIdDeep(JSON.parse(text), wanted);
+    if (found) return found;
+  } catch { /* not JSON */ }
+  for (const line of text.split("\n")) {
+    const at = line.indexOf(wanted);
+    if (at < 0) continue;
+    const outsideName = `${line.slice(0, at)} ${line.slice(at + wanted.length)}`;
+    for (const token of outsideName.trim().split(/\s+/)) {
+      if (isAppIdToken(token)) return token;
+    }
+  }
+  return null;
+}
+
+function isAppIdToken(token: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{5,}$/.test(token) && /[0-9_-]/.test(token);
+}
+
+function findNamedIdDeep(value: unknown, name: string): string | null {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findNamedIdDeep(item, name);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (!value || typeof value !== "object") return null;
+  const obj = value as Record<string, unknown>;
+  const named = ["name", "app_name", "appName", "title"].some(
+    (key) => typeof obj[key] === "string" && (obj[key] as string).trim() === name,
+  );
+  if (named) {
+    const id = findIdDeep(obj);
+    if (id) return id;
+  }
+  for (const nested of Object.values(obj)) {
+    const found = findNamedIdDeep(nested, name);
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * `liveware app list` → the id of an existing app with this name, or null.
+ * Best-effort by contract: an exec failure or unreadable output resolves to null
+ * so the caller falls back to `app create` instead of failing the whole flow.
+ */
+export async function livewareAppFindByName(opts: {
+  livewarePath: string;
+  name: string;
+  execFileFn?: ExecFileLike;
+  log?: LivewareLogger;
+}): Promise<string | null> {
+  const execFileFn = opts.execFileFn ?? nodeExecFile;
+  const stdout = await new Promise<string | null>((resolve) => {
+    execFileFn(
+      opts.livewarePath,
+      ["app", "list"],
+      { timeout: CLI_TIMEOUT_MS },
+      (err, out, errOut) => {
+        if (err) {
+          opts.log?.debug?.(
+            `liveware-sample: app list failed; falling back to app create: ${String(errOut || out || err)}`,
+          );
+          resolve(null);
+          return;
+        }
+        resolve(String(out ?? ""));
+      },
+    );
+  });
+  return stdout == null ? null : findAppIdByName(stdout, opts.name);
+}
+
 export async function livewareAppCreate(opts: {
   livewarePath: string;
   name: string;
@@ -379,7 +594,7 @@ export type LivewareSampleStoreLike = {
   updateLivewareSampleStatus(input: {
     platform: string;
     accountId: string;
-    status: "active" | "failed" | "disabled";
+    status: "pending" | "active" | "failed" | "disabled";
     lastError?: string | null;
   }): void;
   markLivewareSampleIntroSent(input: { platform: string; accountId: string }): void;
@@ -428,10 +643,15 @@ const INTRO_MAX_TRIES = 20;
 const START_RETRY_DELAYS_MS = [30_000, 60_000, 120_000, 300_000];
 
 export class LivewareSampleSupervisor {
-  private readonly deps: LivewareSampleSupervisorDeps;
+  /** Not readonly: adoptDeps() re-points a live supervisor at a re-entered
+   * gateway closure (fresh token / REST client / owner-notify path). */
+  private deps: LivewareSampleSupervisorDeps;
   private serverChild: ChildProcess | null = null;
   private tunnelChild: ChildProcess | null = null;
   private stopped = false;
+  /** True while a startAttempt chain (bootstrap/relaunch) is running; read by
+   * isIdle() so adoptDeps never starts a second concurrent flow. */
+  private launchInFlight = false;
   private restartTimes: number[] = [];
   private timers = new Set<ReturnType<typeof setTimeout>>();
   /** Bumped on every (re)launch and on killChildren: a child's exit handler
@@ -449,8 +669,40 @@ export class LivewareSampleSupervisor {
     await this.startAttempt(0);
   }
 
+  /** Re-point a live supervisor at a freshly re-entered gateway closure, and —
+   * only when nothing is in flight — kick a new attempt.
+   *
+   * `startOpenclawClawlingGateway` re-enters itself on token refresh / transport
+   * backoff, so runtime.ts keeps ONE supervisor per (abortSignal, account) and
+   * hands the new closure here instead of constructing a second supervisor: two
+   * supervisors raced the bootstrap "account has zero apps" gate and registered
+   * two liveware apps for the same account, one of which no row then tracked.
+   * The re-entered closure owns the fresh token, REST client and owner-notify
+   * path; children, timers and the crash-restart budget keep running untouched.
+   * A flow already mid-await finishes on the deps it captured. */
+  adoptDeps(deps: LivewareSampleSupervisorDeps): void {
+    this.deps = deps;
+    // A re-entry used to re-run the whole flow through the brand-new supervisor,
+    // which is what healed an attempt that had skipped (no token yet) or burnt
+    // through its retry ladder. Keep that healing, but only when there is
+    // genuinely nothing live: no in-flight flow, no pending retry/crash-restart
+    // timer, no children — a second concurrent flow is exactly the duplicate
+    // registration the single-supervisor registry exists to prevent.
+    if (this.isIdle()) void this.startAttempt(0);
+  }
+
+  /** Nothing running and nothing scheduled: safe to (re)start a flow. */
+  private isIdle(): boolean {
+    return !this.stopped
+      && !this.launchInFlight
+      && this.timers.size === 0
+      && this.serverChild === null
+      && this.tunnelChild === null;
+  }
+
   private async startAttempt(attempt: number): Promise<void> {
     const { deps } = this;
+    this.launchInFlight = true;
     try {
       if (!deps.enabled) return;
       // ensureLivewareCli downloads the CLI asynchronously on first boot;
@@ -480,6 +732,8 @@ export class LivewareSampleSupervisor {
         `clawchat-plugin-openclaw liveware-sample start failed (attempt ${attempt + 1}, retrying in ${delayMs / 1000}s): ${String(err)}`,
       );
       this.schedule(() => { void this.startAttempt(attempt + 1); }, delayMs);
+    } finally {
+      this.launchInFlight = false;
     }
   }
 
@@ -493,7 +747,7 @@ export class LivewareSampleSupervisor {
   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 */ }
+      killProcessTree(child, this.deps.execFileFn);
     }
     this.serverChild = null;
     this.tunnelChild = null;
@@ -518,17 +772,16 @@ export class LivewareSampleSupervisor {
   private async bootstrap(): Promise<void> {
     const { deps } = this;
     if (this.stopped) return;
+    // Retryable-vs-opt-out: a missing CLI, an absent token and a flaky listApps
+    // are all transient, but they used to `return`, which left the sample dormant
+    // for the whole process lifetime (nothing re-enters bootstrap on its own).
+    // Throw instead so startAttempt's START_RETRY_DELAYS_MS ladder gets its turn;
+    // only a genuine opt-out (disabled row, owner already has apps) returns.
     const livewarePath = deps.resolveLivewarePath();
-    if (!livewarePath) { deps.log?.warn?.("liveware-sample: liveware CLI not ready; skip"); return; }
+    if (!livewarePath) throw new Error("liveware CLI not ready");
     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 (!token) throw new Error("no ClawChat token available yet");
+    const apps = await deps.listApps();
     if (this.bailIfStopped()) return;
     if (apps.apps.length > 0) {
       deps.log?.debug?.("liveware-sample: user already has liveware apps; skip");
@@ -546,9 +799,30 @@ export class LivewareSampleSupervisor {
     this.serverChild = server.child;
     if (this.bailIfStopped()) return;
     await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
-    const appId = await livewareAppCreate({
+    // Reuse an app we already own before minting another one. `app create` is not
+    // idempotent and nothing here ever reconciled against the liveware side, so
+    // every bootstrap that died past this point (no row was written until the very
+    // end, see below) left one more orphan app behind and ate into the account's
+    // app quota. Best-effort: an unreadable list falls through to `app create`.
+    const existingAppId = await livewareAppFindByName({
+      livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn, log: deps.log,
+    });
+    if (this.bailIfStopped()) return;
+    if (existingAppId) {
+      deps.log?.debug?.(`liveware-sample: reusing existing liveware app ${existingAppId}`);
+    }
+    const appId = existingAppId ?? await livewareAppCreate({
       livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn,
     });
+    // Persist the app id BEFORE the steps that can still fail. Without this a
+    // failure anywhere below left no row at all, so the next boot ran bootstrap
+    // again and created yet another app; a "pending" row makes the next attempt
+    // resume through relaunch() with the same app id instead.
+    deps.store.upsertLivewareSample({
+      platform: deps.platform, accountId: deps.accountId,
+      appId, appName: LIVEWARE_SAMPLE_APP_NAME, port: server.port,
+      publicUrl: null, sampleVersion: version, status: "pending",
+    });
     const publicUrl = await tunnelBind({
       livewarePath, appId, port: server.port, execFileFn: deps.execFileFn,
     });
@@ -570,20 +844,22 @@ export class LivewareSampleSupervisor {
   private async relaunch(row: LivewareSampleRow): Promise<void> {
     const { deps } = this;
     if (this.stopped) return;
+    // Both of these used to `return` and strand the sample until the next process
+    // start; they are transient, so throw and let the retry ladder run (see
+    // bootstrap). Only a successful list that no longer contains the app is an
+    // opt-out.
     const livewarePath = deps.resolveLivewarePath();
-    if (!livewarePath) { deps.log?.warn?.("liveware-sample: liveware CLI not ready; skip relaunch"); return; }
+    if (!livewarePath) throw new Error("liveware CLI not ready");
+    const apps = await deps.listApps();
     // 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)}`);
+    // Exception: a "pending" row was persisted mid-bootstrap, before the app was
+    // ever registered with ClawChat, so its absence from this list means "not
+    // registered yet", not "deleted" — disabling it there would strand the app id.
+    if (row.status !== "pending" && !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;
     }
     if (this.bailIfStopped()) return;
@@ -607,21 +883,59 @@ export class LivewareSampleSupervisor {
     });
     this.serverChild = server.child;
     if (this.bailIfStopped()) return;
+    // Re-login before touching the CLI. Its credentials live in $HOME/.clawling,
+    // a different volume from the stateDir holding the row that sent us down this
+    // path: a container that persists stateDir but not $HOME comes back with a row
+    // AND a logged-out CLI, so every tunnelBind/agent below fails auth until the
+    // retry ladder gives up — the sample then never returns for the whole process
+    // lifetime. `login` is idempotent; best-effort, so a stale token still falls
+    // through to whatever credentials the CLI already has.
+    const token = deps.resolveToken();
+    if (token) {
+      try {
+        await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
+      } catch (err) {
+        deps.log?.warn?.(
+          `liveware-sample: relaunch re-login failed; continuing with cached CLI credentials: ${String(err)}`,
+        );
+      }
+      if (this.bailIfStopped()) return;
+    } else {
+      deps.log?.debug?.("liveware-sample: no token; relaunch without re-login");
+    }
+    // Kept after the re-login above so the lookup runs against a CLI that is
+    // actually authenticated: a pending row's app id came straight from
+    // `app create`'s parser and was never confirmed by the liveware side, so
+    // prefer a by-name lookup — a mis-parsed id then self-heals instead of
+    // failing every tunnel bind for the rest of this row's life.
+    let appId = row.app_id;
+    if (row.status === "pending") {
+      const found = await livewareAppFindByName({
+        livewarePath, name: row.app_name, execFileFn: deps.execFileFn, log: deps.log,
+      });
+      if (found && found !== appId) {
+        deps.log?.warn?.(`liveware-sample: pending app id ${appId} not listed; adopting ${found}`);
+        appId = found;
+      }
+      if (this.bailIfStopped()) return;
+    }
     const publicUrl = await tunnelBind({
-      livewarePath, appId: row.app_id, port: server.port, execFileFn: deps.execFileFn,
+      livewarePath, appId, port: server.port, execFileFn: deps.execFileFn,
     });
     if (this.bailIfStopped()) return;
     const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn });
     this.tunnelChild = agent.child;
     if (this.bailIfStopped()) return;
-    if (publicUrl !== row.public_url) {
+    // A pending row has never been registered with ClawChat (public_url is null),
+    // so this condition also covers "register it for the first time".
+    if (publicUrl !== row.public_url || appId !== row.app_id) {
       await deps.registerApp({
-        name: row.app_name, appId: row.app_id, url: publicUrl,
+        name: row.app_name, appId, url: publicUrl,
       });
     }
     deps.store.upsertLivewareSample({
       platform: deps.platform, accountId: deps.accountId,
-      appId: row.app_id, appName: row.app_name, port: server.port,
+      appId, appName: row.app_name, port: server.port,
       publicUrl, sampleVersion: version, status: "active",
     });
     this.watchChildren();
@@ -652,16 +966,25 @@ export class LivewareSampleSupervisor {
           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),
-          });
-        });
+        // This relaunch does NOT go through startAttempt, so it must do that
+        // method's launchInFlight bookkeeping itself: the timer has already been
+        // dropped from `timers` and children are only assigned a few awaits in, so
+        // without this isIdle() reports idle for the whole early part of a
+        // crash-restart and a concurrent adoptDeps kick would run a SECOND launch
+        // flow — the duplicate registration the single-supervisor rule prevents.
+        this.launchInFlight = true;
+        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),
+            });
+          })
+          .finally(() => { this.launchInFlight = false; });
       }, delay);
     };
     for (const child of [this.serverChild, this.tunnelChild]) {