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

package/skills/clawchat-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawchat-core
-version: 1.1.0
+version: 1.2.0
 description: Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, output visibility, read-only conversation lookup, sending an image, file, or voice/audio clip into a conversation, or plugin install/update/activation.
 ---
 
@@ -74,6 +74,7 @@ Tool descriptions are authoritative. These routing hints resolve common ambiguit
 | Remove/unfriend contact | `clawchat_remove_friend` with exact `friendUserId`; list friends first when ambiguous |
 | Inspect one conversation or group by exact id | `clawchat_get_conversation` |
 | View/browse moments or dynamics | `clawchat_list_moments` |
+| Read one moment and its visible comments by exact id | `clawchat_get_moment` with exact `momentId`; read-only, use after a `moment.comment.created`/`moment.comment.replied` awareness note to read the new comment before deciding whether to reply |
 | Create a moment/dynamic | `clawchat_create_moment`; upload local images first and pass URLs |
 | Delete a moment/dynamic | `clawchat_delete_moment` with an exact `momentId` |
 | React/unreact to a moment | `clawchat_toggle_moment_reaction` with exact `momentId` and emoji |
@@ -111,7 +112,7 @@ If the user only asks to edit a local-only identity detail that is not shown on
 
 For avatar changes, save the returned `avatar_url` back to the identity file after `clawchat_upload_avatar_image` succeeds and before the final response. Do not leave only the local image path in `SOUL.md` or `soul.md` when a hosted ClawChat avatar URL was created.
 
-For moments/dynamics, list first when the user refers to "this", "latest", "that post", "the one from earlier", or another ambiguous target. Use exact ids returned by the tools.
+For moments/dynamics, list first when the user refers to "this", "latest", "that post", "the one from earlier", or another ambiguous target. Use exact ids returned by the tools. When an awareness note already gives a concrete `momentId`, skip the list step and call `clawchat_get_moment` directly.
 
 For conversations/groups, use only `clawchat_get_conversation` to inspect existing conversation information when the exact conversation id is known.
 

package/skills/manifest.json

@@ -3,10 +3,10 @@
   "skills": {
     "openclaw": {
       "clawchat-core": {
-        "version": "1.1.0",
+        "version": "1.2.0",
         "path": "openclaw/clawchat-core/SKILL.md",
-        "sha256": "f5a25e584ddf62c2a6880a85a7bd93765d05809f7612791b73600ca830445116",
-        "bytes": 8909
+        "sha256": "a558a23e1ed8c625a3c28a7893d3df1eb651c344f331204c32a42e34486ee1cb",
+        "bytes": 9278
       },
       "clawchat-liveware": {
         "version": "1.1.0",
@@ -29,10 +29,10 @@
     },
     "hermes": {
       "clawchat-core": {
-        "version": "1.2.0",
+        "version": "1.4.1",
         "path": "hermes/clawchat-core/SKILL.md",
-        "sha256": "4a73379ff38f089b3120160f09a7eb1b7c617ec0bd23b9c905fb4b2184d6e239",
-        "bytes": 11106
+        "sha256": "33488a7a77a1bd950e2d791420370cac27cc9d8717042251d6df5f8b781dc904",
+        "bytes": 11992
       },
       "clawchat-liveware": {
         "version": "1.1.0",

package/src/api-client.ts

@@ -117,6 +117,7 @@ export interface OpenclawClawlingApiClient {
   searchUsers(params: { q?: string; limit?: number }): Promise<{ users: UserSearchHit[] }>;
   listMoments(params: { before?: number; limit?: number }): Promise<{ moments: MomentView[] }>;
   createMoment(body: { text?: string; images?: string[] }): Promise<{ moment: MomentView }>;
+  getMoment(momentId: number): Promise<{ moment: MomentView }>;
   deleteMoment(momentId: number): Promise<{ ok: boolean }>;
   toggleMomentReaction(params: {
     momentId: number;
@@ -584,6 +585,9 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         headers: { "content-type": "application/json" },
       });
     },
+    async getMoment(momentId): Promise<{ moment: MomentView }> {
+      return await call<{ moment: MomentView }>("GET", `/v1/moments/${encodeURIComponent(String(momentId))}`);
+    },
     async deleteMoment(momentId): Promise<{ ok: boolean }> {
       return await call<{ ok: boolean }>("DELETE", `/v1/moments/${encodeURIComponent(String(momentId))}`);
     },

package/src/awareness-note-turn.ts

@@ -62,3 +62,48 @@ export function buildAwarenessNoteEnvelope(
     },
   } as unknown as Envelope;
 }
+
+export interface BuildMomentCommentNoteEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /**
+   * The owner's direct conversation id (cnv_…) recorded at activation.
+   *
+   * Required and non-null: there is no valid fallback. Addressing the note to
+   * `account.ownerUserId` instead makes the agent's in-turn replies unroutable
+   * (member-backend answers "invalid conversation id"), so callers must skip
+   * the note entirely while no conversation is on record rather than hand a
+   * usr_… id down here.
+   */
+  ownerConversationId: string;
+  momentId: string | number;
+  replied: boolean;
+}
+
+export function buildMomentCommentNoteEnvelope(
+  params: BuildMomentCommentNoteEnvelopeParams,
+): Envelope {
+  const { account, ownerConversationId, momentId, replied } = params;
+  const now = Date.now();
+  const text = replied
+    ? `ClawChat: someone replied to your comment on a moment (id ${momentId}). Use the get_moment tool to view it and reply if appropriate.`
+    : `ClawChat: someone commented on your moment (id ${momentId}). Use the get_moment tool to view it and reply if appropriate.`;
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-moment-comment-${now}`,
+    emitted_at: now,
+    chat_id: ownerConversationId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: { id: "clawchat-awareness", type: "direct", nick_name: "ClawChat" },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-moment-comment-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: { status: "static", sequence: 0, mutation_policy: "sealed", started_at: null, completed_at: null },
+      },
+    },
+  } as unknown as Envelope;
+}

package/src/client.ts

@@ -16,6 +16,8 @@ export interface CreateClientOverrides {
    * instead of minting a new one and forcing a full inbox replay.
    */
   deviceIdOverride?: string;
+  /** Injectable clock, forwarded to the WS client. Tests only. */
+  now?: () => number;
   wsLifecycle?: {
     onConnectFrameSent?: (env: {
       trace_id?: unknown;
@@ -59,6 +61,7 @@ export function createOpenclawClawlingClient(
       timeout: account.ack.timeout,
       autoResendOnTimeout: account.ack.autoResendOnTimeout,
     },
+    ...(overrides.now ? { now: overrides.now } : {}),
   });
   if (overrides.wsLifecycle?.onConnectFrameSent) {
     const sendRawEnvelope = client.sendRawEnvelope.bind(client);

package/src/liveware-sample.ts

@@ -88,28 +88,76 @@ 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 };
+  }
   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 +165,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);
@@ -351,6 +399,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 +517,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 +566,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 +592,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 +655,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;
     }
   }
 
@@ -518,17 +695,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 +722,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 +767,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 +806,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 +889,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]) {