create-opentray 0.27.4 → 0.28.0

package/dist/{bin-DgadYsE1.mjs → bin-BEqHk5dQ.mjs}

@@ -7587,7 +7587,9 @@ const TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS = 300;
 * The generated-entry helper source. The embedding template supplies
 * `column`/`fixed`/`grow` (imported from "@opentray/ext-webview" beside
 * `WebviewExt`) — the carrier deliberately performs no imports of its own so
-* both templates stay single-import consumers of the facade.
+* both templates stay single-import consumers of the facade. The template
+* also injects `options.log` (runtime notes) and `options.event` (structured
+* bootstrap-milestone sink into app.log, harden-lifecycle-ownership D5).
 */
 const toolbarCarrierSource = () => `// Toolbar navigation carrier (add-webview-orchestration plan D12/D13):
 // composes the native navigation toolbar over one content webview and drives
@@ -7597,18 +7599,42 @@ const toolbarCarrierSource = () => `// Toolbar navigation carrier (add-webview-o
 const TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS = ${TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS};
 
 const attachToolbarCarrier = async (shell, options) => {
+  // Bootstrap milestones (harden-lifecycle-ownership D5): one structured
+  // record per carrier step through the embedding template's event sink
+  // (app.log). Failure records are awaited so the failed step is durable
+  // before the error aborts the bootstrap; ok records are best-effort but
+  // still ordered — the sink is the template's serial append queue (Codex R2
+  // P1), whose submission is synchronous, so a void call enters the same
+  // happens-before chain and lands after every earlier record. Keep the ok
+  // path void: the carrier's awaited per-step bootstrap structure is
+  // unchanged and the queue owns the ordering.
+  const event = typeof options.event === "function" ? options.event : () => {};
+  const milestone = async (step, run) => {
+    try {
+      const value = await run();
+      void event({ step, status: "ok" });
+      return value;
+    } catch (error) {
+      await event({
+        step,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  };
   // Per-child bridge policy (D2): the toolbar page is trusted shell UI and
   // gets exactly the channel surface; the content webview gets NO policy, so
   // it is bridgeless regardless of what it loads.
-  await shell.createWebview({
+  await milestone("createWebviewToolbar", () => shell.createWebview({
     id: "toolbar",
     url: options.toolbarUrl,
     bridge: { webviewId: true, messageChannels: true },
-  });
-  const content = await shell.createWebview({ id: "content", url: options.contentUrl });
+  }));
+  const content = await milestone("createWebviewContent", () => shell.createWebview({ id: "content", url: options.contentUrl }));
   // Declarative layered layout (D8 sugar): toolbar pinned at a fixed 44px
   // height, content filling the remainder; resize is recomputed natively.
-  await shell.setLayout(column([fixed("toolbar", 44), grow("content")]));
+  await milestone("setLayout", () => shell.setLayout(column([fixed("toolbar", 44), grow("content")])));
   const note = (error) => {
     const message = error instanceof Error ? error.message : String(error);
     void options.log("toolbar carrier: " + message);
@@ -7736,7 +7762,9 @@ const attachToolbarCarrier = async (shell, options) => {
     }, TOOLBAR_CHANNEL_REBUILD_DEBOUNCE_MS);
   };
 
-  await openChannel();
+  // The bootstrap channel gets the milestone record; self-heal rebuilds above
+  // stay unrecorded (P1-3 steady-state, not bootstrap).
+  await milestone("openChannel", openChannel);
   return {
     content,
     stop: () => {
@@ -7750,6 +7778,197 @@ const attachToolbarCarrier = async (shell, options) => {
 };
 `;
 //#endregion
+//#region packages/core/src/log-queue.ts
+/** The generated-entry app.log append queues. The milestone chain replaces
+* the old fire-and-forget `appendFile.bind(undefined, appLogPath)` logSink:
+* submission order becomes disk order and exits can await the drain. The
+* bounded output channel keeps a supervised command's stream from costing
+* unbounded memory or exit latency — lossy-by-design, with every loss
+* counted and reported (Codex R4). */
+const logQueueSource = () => `// App.log append queues (Codex R2 P1 + R3 + R4, 2026-09-15): appendFile
+// completions have no happens-before, so milestone records must never race,
+// and child output must never share that chain — a noisy child would grow an
+// unbounded happens-before list, drag later milestones, and make the exit
+// flush unbounded. Milestones keep one strictly serial chain; output records
+// flow through their own chain, coalesced and byte-capped.
+const appendLogLine = process.env.OPENTRAY_TEST_LOG_JITTER === "1"
+  ? async (text) => {
+      // Test seam only: random 0-30 ms per-append delay.
+      await new Promise((resolveDelay) => { setTimeout(resolveDelay, Math.random() * 30); });
+      await appendFile(appLogPath, text, "utf8");
+    }
+  : (text) => appendFile(appLogPath, text, "utf8");
+let logQueueTail = Promise.resolve();
+const logSink = (text) => {
+  const write = logQueueTail.then(() => appendLogLine(text));
+  // A failed append must not kill the chain; the write itself still rejects
+  // for callers that await durability (the tail catch also keeps void-ed
+  // submissions from becoming unhandled rejections).
+  logQueueTail = write.catch(() => {});
+  return write;
+};
+
+// Bounded child-output channel (Codex R3, hardened R4). Two chains coexist:
+// milestones stay strictly ordered among themselves, output records among
+// themselves; cross-channel disk order is unspecified (each appendFile is one
+// O_APPEND write, so records interleave at line boundaries but never corrupt).
+//
+// LOSS CONTRACT (Codex R4): child output in app.log is lossy-by-design
+// diagnostic data; every loss is counted and reported. Losses happen in
+// exactly three counted ways: (1) whole-chunk drops at admission or commit
+// trim that hold the cap, (2) an output append that rejects or exceeds
+// OUTPUT_APPEND_TIMEOUT_MS — its raw bytes re-enter the pending count, and a
+// late success after a timeout is conservative over-counting, never
+// under-counting, and (3) chunks absorbed after beginOutputShutdown() that no
+// bounded flush round managed to carry. Every counted loss resurfaces as one
+// readable "[log-queue] dropped N output bytes" line on the next carrier that
+// lands.
+const OUTPUT_COMMIT_BYTES = 8192;
+const OUTPUT_COMMIT_IDLE_MS = 50;
+const OUTPUT_CAP_BYTES = 262144;
+// Output-append wall-clock bound: a hung appendFile cannot hang the exit
+// flush. OPENTRAY_TEST_LOG_APPEND_TIMEOUT_MS is the test seam that shrinks it.
+const OUTPUT_APPEND_TIMEOUT_MS = Number(process.env.OPENTRAY_TEST_LOG_APPEND_TIMEOUT_MS) > 0
+  ? Number(process.env.OPENTRAY_TEST_LOG_APPEND_TIMEOUT_MS)
+  : 5000;
+const FLUSH_MAX_DRAIN_ROUNDS = 8;
+const outputChunks = [];
+let outputBufferedBytes = 0;
+let outputInFlightBytes = 0;
+// Drop accounting (Codex R4 P1): pending = counted losses no carrier has
+// taken yet; the in-flight figure = losses a submitted carrier is reporting
+// right now. A commit MOVES pending into its carrier's reservation, and only
+// that carrier's own completion retires or returns it, so concurrent commits
+// can never double-carry an episode or drive the accounting negative (the
+// old single global counter subtracted stale snapshots and suppressed later
+// markers).
+let outputDroppedBytesPending = 0;
+let outputInFlightDropBytes = 0;
+let outputShutdown = false;
+let outputTimer = null;
+let outputTail = Promise.resolve();
+// One output append, wall-clock bounded. Resolves true when landed, false
+// when rejected or timed out (the bytes then count as lost).
+const appendOutputBounded = (payload) => new Promise((resolveWrite) => {
+  let settled = false;
+  const timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    resolveWrite(false);
+  }, OUTPUT_APPEND_TIMEOUT_MS);
+  appendLogLine(payload).then(
+    () => { if (!settled) { settled = true; clearTimeout(timer); resolveWrite(true); } },
+    () => { if (!settled) { settled = true; clearTimeout(timer); resolveWrite(false); } },
+  );
+});
+const commitOutputBuffer = () => {
+  if (outputTimer !== null) { clearTimeout(outputTimer); outputTimer = null; }
+  if (outputChunks.length === 0 && outputDroppedBytesPending === 0) return;
+  const carriedDrops = outputDroppedBytesPending;
+  outputDroppedBytesPending = 0;
+  outputInFlightDropBytes += carriedDrops;
+  const marker = carriedDrops > 0
+    ? "[log-queue] dropped " + carriedDrops + " output bytes\\n"
+    : "";
+  // Marker bytes count inside the cap (Codex R4 P2): the whole submitted
+  // payload — marker included — must fit the budget not yet taken by
+  // in-flight appends. Whole oldest chunks that do not fit drop now and join
+  // the NEXT carrier's count (one chunk is the drop granularity everywhere).
+  if (Buffer.byteLength(marker) > OUTPUT_CAP_BYTES - outputInFlightBytes) {
+    // Even the marker alone does not fit (in-flight holds the full cap):
+    // return the episode to pending and keep the chunks buffered; the flush
+    // drain loop retries once the held appends land.
+    outputDroppedBytesPending += carriedDrops;
+    outputInFlightDropBytes -= carriedDrops;
+    if (outputBufferedBytes > 0) { outputTimer = setTimeout(commitOutputBuffer, OUTPUT_COMMIT_IDLE_MS); }
+    return;
+  }
+  while (outputChunks.length > 0
+      && Buffer.byteLength(marker) + outputBufferedBytes > OUTPUT_CAP_BYTES - outputInFlightBytes) {
+    const oldest = outputChunks.shift();
+    const size = Buffer.byteLength(oldest);
+    outputBufferedBytes -= size;
+    outputDroppedBytesPending += size;
+  }
+  const text = outputChunks.join("");
+  outputChunks.length = 0;
+  outputBufferedBytes = 0;
+  const rawBytes = Buffer.byteLength(text);
+  const payloadBytes = Buffer.byteLength(marker) + rawBytes;
+  outputInFlightBytes += payloadBytes;
+  const write = outputTail.then(() => appendOutputBounded(marker + text));
+  write.then((landed) => {
+    outputInFlightBytes -= payloadBytes;
+    if (landed) {
+      // The drop record is durable only now that its carrier append landed.
+      outputInFlightDropBytes -= carriedDrops;
+    } else {
+      // Lossy-by-design (Codex R4): a rejected or timed-out carrier returns
+      // its episode to pending and counts its own raw bytes as dropped, so
+      // the next successful carrier re-reports the full total.
+      outputInFlightDropBytes -= carriedDrops;
+      outputDroppedBytesPending += carriedDrops + rawBytes;
+    }
+  });
+  outputTail = write.then(() => {});
+};
+const beginOutputShutdown = () => { outputShutdown = true; };
+const logOutputChunk = (text) => {
+  const size = Buffer.byteLength(text);
+  if (outputShutdown) {
+    // Quiescence barrier (Codex R4): after shutdown begins, chunks never
+    // enter the chain and never schedule commits — their bytes join the
+    // count the final flush marker carries.
+    outputDroppedBytesPending += size;
+    return;
+  }
+  outputChunks.push(text);
+  outputBufferedBytes += size;
+  // Hard cap BEFORE the coalescing thresholds: over-cap data must drop, not
+  // graduate into an in-flight append that only the disk can drain. One
+  // whole chunk is the granularity: a single chunk larger than the cap drops
+  // whole (its byte count lands in the marker), and the transient memory
+  // bound is cap + largest single chunk.
+  while (outputBufferedBytes + outputInFlightBytes > OUTPUT_CAP_BYTES && outputChunks.length > 0) {
+    const oldest = outputChunks.shift();
+    const droppedSize = Buffer.byteLength(oldest);
+    outputBufferedBytes -= droppedSize;
+    outputDroppedBytesPending += droppedSize;
+  }
+  if (outputTimer !== null) { clearTimeout(outputTimer); outputTimer = null; }
+  if (outputBufferedBytes >= OUTPUT_COMMIT_BYTES) {
+    commitOutputBuffer();
+  } else if (outputBufferedBytes > 0) {
+    outputTimer = setTimeout(commitOutputBuffer, OUTPUT_COMMIT_IDLE_MS);
+  }
+};
+const flushLogQueue = async () => {
+  // Bounded drain (Codex R4): each round commits what fits and awaits BOTH
+  // chain snapshots; if anything new was submitted — or drops are still
+  // uncarried — the next round picks it up, for at most FLUSH_MAX_DRAIN_ROUNDS
+  // rounds. Flush is a barrier with a budget: it always resolves, even over a
+  // rejecting or hung appendFile (each output append is wall-clock bounded
+  // and its loss is counted). Milestone awaits stay bounded by appendFile
+  // itself, which remains the durability contract for milestone records.
+  for (let round = 0; round < FLUSH_MAX_DRAIN_ROUNDS; round += 1) {
+    const logBefore = logQueueTail;
+    const outBefore = outputTail;
+    commitOutputBuffer();
+    await logQueueTail;
+    await outputTail;
+    if (logQueueTail === logBefore && outputTail === outBefore
+        && outputChunks.length === 0 && outputDroppedBytesPending === 0) {
+      return;
+    }
+  }
+  // Round budget exhausted while output was still arriving: give the final
+  // counted total one last bounded carrier instead of dropping it silently.
+  commitOutputBuffer();
+  await logQueueTail;
+  await outputTail;
+};
+`;
+//#endregion
 //#region packages/core/src/entry-template.ts
 /** The generated app entry: supervises the command, owns tray + window. */
 const createEntrySource = (config) => {
@@ -7785,8 +8004,13 @@ const config = ${JSON.stringify(config, null, 2)};
 
 const appLogPath = resolve(PROJECT_DIR, "app.log");
 await mkdir(dirname(appLogPath), { recursive: true });
-const logSink = appendFile.bind(undefined, appLogPath);
+${logQueueSource()}
 const logNote = (message) => { void logSink("[create-opentray] " + message + "\\n", "utf8"); };
+// Bootstrap milestones (harden-lifecycle-ownership D5): one structured JSON
+// record per startup step — the operator reads session health from app.log
+// alone, and a failed step names itself instead of needing archaeology.
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+const logEvent = (record) => logSink(JSON.stringify({ time: new Date().toISOString(), event: "bootstrap", ...record }) + "\\n", "utf8");
 const sleep = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 
 const shellOptions = ${JSON.stringify(config.shell ?? null)};
@@ -7875,6 +8099,11 @@ const main = async () => {
   // from the same host (its navigation surface stays channel-only, D12).
   const shellApi = await import("./app-shell-server.mjs");
   const shellPort = await shellApi.listenShell();
+  if (shellPort === null) {
+    await logEvent({ step: "listenShell", status: "failed" });
+  } else {
+    void logEvent({ step: "listenShell", status: "ok", port: shellPort });
+  }
 
   // Command supervision state shared by the exit note and teardown.
   let commandExited = false;
@@ -7900,7 +8129,9 @@ const main = async () => {
     });
     shellApi.registerPty(pty);
     pty.onData((chunk) => {
-      void logSink(chunk, "utf8");
+      // Child output is bounded-channel data (Codex R3), never a milestone
+      // record — a noisy command must not tax the serial chain.
+      logOutputChunk(chunk);
       shellApi.pushOutput(chunk);
     });
     const exited = new Promise((resolvePromise) => {
@@ -7923,8 +8154,8 @@ const main = async () => {
     });
     child.stdout.setEncoding("utf8");
     child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk) => { void logSink(chunk, "utf8"); shellApi.pushOutput(chunk); });
-    child.stderr.on("data", (chunk) => { void logSink(chunk, "utf8"); shellApi.pushOutput(chunk); });
+    child.stdout.on("data", (chunk) => { logOutputChunk(chunk); shellApi.pushOutput(chunk); });
+    child.stderr.on("data", (chunk) => { logOutputChunk(chunk); shellApi.pushOutput(chunk); });
     const exited = new Promise((resolvePromise) => {
       child.once("exit", (code, signal) => resolvePromise({ code, signal }));
     });
@@ -7944,7 +8175,7 @@ const main = async () => {
 
   const tray = await (async () => {
     try {
-      return await createTray({
+      const created = await createTray({
         id: config.appId,
         tooltip: { title: config.appName, description: \`\${config.appName} (OpenTray)\` },
         icon: Object.keys(trayIconCandidates).length > 0
@@ -7967,6 +8198,8 @@ const main = async () => {
           cwd: PROJECT_DIR,
         },
       });
+      void logEvent({ step: "createTray", status: "ok", appId: config.appId });
+      return created;
     } catch (error) {
       // Carrier-resurrection yield: a Dock-pinned carrier can cold-start this
       // entry while another instance already owns the broker session. The
@@ -7979,12 +8212,29 @@ const main = async () => {
       if (message.includes("OPENTRAY_BROKER_SINGLE_SESSION")) {
         await logSink("[create-opentray] broker session already owned by another instance of this app; this cold-started launcher exits (yield)\\n", "utf8");
         try { command.killDirect(); } catch { /* already dead */ }
+        await flushLogQueue();
         process.exit(0);
       }
       throw error;
     }
   })();
 
+  // harden-lifecycle-ownership D3: broker connection death is a terminal
+  // state. The entry records the milestone and exits non-zero — the
+  // supervised command dies with its supervisor instead of outliving a dead
+  // backend. The quitting flag keeps the graceful quit path (whose transport
+  // close also reaches this terminal state) on its exit(0) course.
+  let quitting = false;
+  tray.onConnectionDead?.((error) => {
+    if (quitting) return;
+    quitting = true;
+    void (async () => {
+      await logEvent({ step: "connectionDead", status: "failed", error: errorText(error) });
+      await flushLogQueue();
+      process.exit(1);
+    })();
+  });
+
   const baseTitle = config.appName;
   // v1 developerMode maps ONLY to per-window DevTools admission. When false it
   // must not request devtools at all — default windows are not inspectable.
@@ -7997,11 +8247,15 @@ const main = async () => {
   // window = its own window session), so dedicated windows never collide on
   // content.
   const serviceWindows = new Map();
+  // harden-lifecycle-ownership D5: a port whose window bootstrap failed is
+  // recorded once (app.log names the failed milestone) and not retried every
+  // monitor tick — a zombie retry loop would bury the failure record.
+  const failedServiceWindows = new Set();
   let terminalWindow = null;
 
   const ensureTerminalWindow = async () => {
     if (terminalWindow !== null || shellPort === null) return terminalWindow;
-    terminalWindow = tray.extend(WebviewExt).createWebviewWindow({
+    const candidate = tray.extend(WebviewExt).createWebviewWindow({
       url: \`http://127.0.0.1:\${shellPort}/terminal.html\`,
       width: 900,
       height: 560,
@@ -8009,7 +8263,18 @@ const main = async () => {
       style: { appMode: true, autoHide: false, keepOnTop: false },
       ...devtools,
     });
-    await terminalWindow.show().catch(() => {});
+    // D5: a failed show leaves no session — record it and keep
+    // terminalWindow null so a later abnormal-exit reveal can retry this
+    // surface against a fresh window.
+    try {
+      await candidate.show();
+      void logEvent({ step: "showWindow", status: "ok", target: "terminal" });
+    } catch (error) {
+      await logEvent({ step: "showWindow", status: "failed", target: "terminal", error: errorText(error) });
+      await candidate.destroy().catch(() => {});
+      return null;
+    }
+    terminalWindow = candidate;
     return terminalWindow;
   };
 
@@ -8026,7 +8291,7 @@ const main = async () => {
   };
 
   const ensureServiceWindow = async (port) => {
-    if (serviceWindows.has(port)) return;
+    if (serviceWindows.has(port) || failedServiceWindows.has(port)) return;
     const direct = \`http://127.0.0.1:\${port}\`;
     // Toolbar service windows (D13): the SAME native carrier URL applications
     // use — a windowOnly session whose toolbar webview (shell-served
@@ -8043,16 +8308,38 @@ const main = async () => {
         style: { appMode: true, autoHide: false, keepOnTop: false },
         ...devtools,
       });
-      await win.show().catch(() => {});
-      const carrier = await attachToolbarCarrier(win, {
-        toolbarUrl: \`http://127.0.0.1:\${shellPort}/toolbar.html\`,
-        contentUrl: direct,
-        titleFollows,
-        log: logNote,
-      });
-      // P1-3 exit race: teardown closes the channel; the carrier must never
-      // rebuild against a dying session. Stop before the window goes down.
-      process.once("exit", carrier.stop);
+      // harden-lifecycle-ownership D5: the show() before the carrier is a
+      // bootstrap gate — a failure aborts (the carrier never attaches child
+      // webviews against a session that never came up) and the structured
+      // record names the failed milestone in app.log.
+      try {
+        await win.show();
+        void logEvent({ step: "showWindow", status: "ok", target: "service", port });
+      } catch (error) {
+        await logEvent({ step: "showWindow", status: "failed", target: "service", port, error: errorText(error) });
+        failedServiceWindows.add(port);
+        await win.destroy().catch(() => {});
+        return;
+      }
+      try {
+        const carrier = await attachToolbarCarrier(win, {
+          toolbarUrl: \`http://127.0.0.1:\${shellPort}/toolbar.html\`,
+          contentUrl: direct,
+          titleFollows,
+          log: logNote,
+          event: logEvent,
+        });
+        // P1-3 exit race: teardown closes the channel; the carrier must never
+        // rebuild against a dying session. Stop before the window goes down.
+        process.once("exit", carrier.stop);
+      } catch {
+        // D5: the carrier already recorded its failed milestone; this window
+        // is dead, the port is not retried, and the supervised command keeps
+        // running (its terminal remains the abnormal-exit surface).
+        failedServiceWindows.add(port);
+        await win.destroy().catch(() => {});
+        return;
+      }
       serviceWindows.set(port, { win, detached: false });
       return;
     }
@@ -8066,8 +8353,16 @@ const main = async () => {
       ...(!titleFollows ? {} : { titleSync: { documentToWindow: true } }),
       ...(!iconFollows ? {} : { iconSync: { faviconToWindow: true } }),
     });
+    try {
+      await win.show();
+      void logEvent({ step: "showWindow", status: "ok", target: "service", port });
+    } catch (error) {
+      await logEvent({ step: "showWindow", status: "failed", target: "service", port, error: errorText(error) });
+      failedServiceWindows.add(port);
+      await win.destroy().catch(() => {});
+      return;
+    }
     serviceWindows.set(port, { win, detached: false });
-    await win.show().catch(() => {});
   };
 
   if (showTerminal) {
@@ -8182,6 +8477,7 @@ const main = async () => {
   }
 
   const quit = async () => {
+    quitting = true;
     for (const { win } of serviceWindows.values()) {
       try { await win.destroy(); } catch {}
     }
@@ -8190,7 +8486,13 @@ const main = async () => {
       try { await terminalWindow.destroy(); } catch {}
     }
     await tray.destroy();
+    // Codex R4 quiescence barrier: from here the output channel can only
+    // drain. Chunks the dying child emits during the kill sweep are counted
+    // into the final drop marker instead of scheduling post-flush commits a
+    // fast process.exit would orphan.
+    beginOutputShutdown();
     await killCommand();
+    await flushLogQueue();
     process.exit(0);
   };
 
@@ -8221,6 +8523,7 @@ main().catch(async (error) => {
     await logSink(\`[create-opentray] startup failed: \${error instanceof Error ? error.stack ?? error.message : String(error)}\\n\`, "utf8");
   } catch { /* app.log unwritable; stderr below is the remaining surface */ }
   console.error(error);
+  await flushLogQueue();
   process.exit(1);
 });
 `;
@@ -8262,8 +8565,13 @@ const iconFollows = config.window.iconFollowsDocument === true;
 
 const appLogPath = resolve(PROJECT_DIR, "app.log");
 await mkdir(dirname(appLogPath), { recursive: true });
-const logSink = appendFile.bind(undefined, appLogPath);
+${logQueueSource()}
 const logNote = (message) => { void logSink("[create-opentray] " + message + "\\n", "utf8"); };
+// Bootstrap milestones (harden-lifecycle-ownership D5): one structured JSON
+// record per startup step — the operator reads session health from app.log
+// alone, and a failed step names itself instead of needing archaeology.
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+const logEvent = (record) => logSink(JSON.stringify({ time: new Date().toISOString(), event: "bootstrap", ...record }) + "\\n", "utf8");
 
 ${toolbarCarrierSource()}const main = async () => {
   let appIcon;
@@ -8290,7 +8598,7 @@ ${toolbarCarrierSource()}const main = async () => {
 
   const tray = await (async () => {
     try {
-      return await createTray({
+      const created = await createTray({
         id: config.appId,
         tooltip: { title: config.appName, description: \`\${config.appName} (OpenTray)\` },
         icon: Object.keys(trayIconCandidates).length > 0
@@ -8312,6 +8620,8 @@ ${toolbarCarrierSource()}const main = async () => {
           cwd: PROJECT_DIR,
         },
       });
+      void logEvent({ step: "createTray", status: "ok", appId: config.appId });
+      return created;
     } catch (error) {
       // Carrier-resurrection yield: a Dock-pinned carrier can cold-start this
       // entry while another instance already owns the broker session. The
@@ -8320,12 +8630,29 @@ ${toolbarCarrierSource()}const main = async () => {
       const message = error instanceof Error ? error.message : String(error);
       if (message.includes("OPENTRAY_BROKER_SINGLE_SESSION")) {
         await logSink("[create-opentray] broker session already owned by another instance of this app; this cold-started launcher exits (yield)\\n", "utf8");
+        await flushLogQueue();
         process.exit(0);
       }
       throw error;
     }
   })();
 
+  // harden-lifecycle-ownership D3: broker connection death is a terminal
+  // state. The entry records the milestone and exits non-zero — it never
+  // keeps a live shell server over a dead backend (zombie entry). The
+  // quitting flag keeps the graceful quit path (whose transport close also
+  // reaches this terminal state) on its exit(0) course.
+  let quitting = false;
+  tray.onConnectionDead?.((error) => {
+    if (quitting) return;
+    quitting = true;
+    void (async () => {
+      await logEvent({ step: "connectionDead", status: "failed", error: errorText(error) });
+      await flushLogQueue();
+      process.exit(1);
+    })();
+  });
+
   // v1 developerMode maps ONLY to per-window DevTools admission. When false it
   // must not request devtools at all — default windows are not inspectable.
   const devtools = config.developerMode === true ? { devtools: true } : {};
@@ -8340,7 +8667,10 @@ ${toolbarCarrierSource()}const main = async () => {
     const shellApi = await import("./app-shell-server.mjs");
     shellPort = await shellApi.listenShell();
     if (shellPort === null) {
+      await logEvent({ step: "listenShell", status: "failed" });
       await logSink("[create-opentray] toolbar shell host failed to listen; opening the direct window\\n", "utf8");
+    } else {
+      void logEvent({ step: "listenShell", status: "ok", port: shellPort });
     }
   }
   const toolbarReady = toolbarMode && shellPort !== null;
@@ -8361,7 +8691,18 @@ ${toolbarCarrierSource()}const main = async () => {
       ...(iconFollows ? { iconSync: { faviconToWindow: true } } : {}),
     }),
   });
-  await window.show().catch(() => {});
+  // harden-lifecycle-ownership D5: the initial show() is a bootstrap gate. A
+  // failure aborts the carrier (no child webviews attach against a session
+  // that never came up) and reaches the startup boundary — app.log records
+  // the failed milestone, then the top-level handler persists the stack and
+  // exits non-zero. Never swallowed.
+  try {
+    await window.show();
+    void logEvent({ step: "showWindow", status: "ok", mode: toolbarReady ? "toolbar" : "direct" });
+  } catch (error) {
+    await logEvent({ step: "showWindow", status: "failed", mode: toolbarReady ? "toolbar" : "direct", error: errorText(error) });
+    throw error;
+  }
 
   let content = null;
   if (toolbarReady) {
@@ -8370,6 +8711,7 @@ ${toolbarCarrierSource()}const main = async () => {
       contentUrl: config.url,
       titleFollows,
       log: logNote,
+      event: logEvent,
     });
     ({ content } = carrier);
     // P1-3 exit race: teardown closes the channel; the carrier must never
@@ -8392,8 +8734,10 @@ ${toolbarCarrierSource()}const main = async () => {
   };
 
   const quit = async () => {
+    quitting = true;
     try { await window.destroy(); } catch {}
     await tray.destroy();
+    await flushLogQueue();
     process.exit(0);
   };
 
@@ -8419,6 +8763,7 @@ main().catch(async (error) => {
     await logSink(\`[create-opentray] startup failed: \${error instanceof Error ? error.stack ?? error.message : String(error)}\\n\`, "utf8");
   } catch { /* app.log unwritable; stderr below is the remaining surface */ }
   console.error(error);
+  await flushLogQueue();
   process.exit(1);
 });
 
@@ -8508,6 +8853,19 @@ const CT = {
   ".json": "application/json",
 };
 
+// Toolbar context-menu guard (user walkthrough finding, 2026-09-15): the
+// trusted shell UI never shows the engine's native context menu except on
+// text-entry elements (inputs keep copy/paste/etc). Injected at serve time
+// into toolbar.html because the macOS native suppression hook stays off by
+// law — the isa-swizzle approach crashed the 0.27.3 broker, and the page
+// layer's own preventDefault is the sanctioned suppression point.
+const TOOLBAR_GUARD =
+  '<script>document.addEventListener("contextmenu",function(e){var t=e.target;' +
+  'if(t instanceof HTMLElement&&t.closest("input,textarea,[contenteditable]:not([contenteditable=\\"false\\"])")){return;}' +
+  'e.preventDefault();},true);<\/script>';
+const injectToolbarGuard = (html) =>
+  html.includes("</head>") ? html.replace("</head>", TOOLBAR_GUARD + "</head>") : TOOLBAR_GUARD + html;
+
 const server = createServer(async (req, res) => {
   const url = new URL(req.url ?? "/", "http://127.0.0.1");
   if (url.pathname === "/api/events") {
@@ -8561,6 +8919,12 @@ const server = createServer(async (req, res) => {
       .end(index);
     return;
   }
+  if (target === join(SHELL_DIR, "toolbar.html")) {
+    res
+      .writeHead(200, { "content-type": CT[".html"], "cache-control": "no-store" })
+      .end(injectToolbarGuard(bytes.toString("utf8")));
+    return;
+  }
   res
     .writeHead(200, {
       "content-type": CT[extname(target).toLowerCase()] ?? "application/octet-stream",
@@ -18616,4 +18980,4 @@ if (isMainModule()) main(process.argv.slice(2)).then((code) => {
 //#endregion
 export { resolveLaunchVector as A, parseLsofPorts as C, verifyHttpService as D, serviceUrl as E, isValidAppId as F, toProjectDirectoryName as I, tokenizeCommandLine as M, deriveDefaultAppId as N, waitForTcpPort as O, deriveDefaultAppName as P, createPortDiscovery as S, parsePowerShellPorts as T, extractTitle as _, createWizardServer as a, resolveFaviconUrl as b, createWizardSession as c, detectPackageManager as d, expectedDarwinBundlePath as f, extractFaviconCandidates as g, writeScaffold as h, parseWizardCli as i, resolveOnPath as j, parseShebangInterpreter as k, openMaterializedApp as l, materialize as m, normalizeDraftForm as n, isAuthorized as o, isDirectoryOccupied$1 as p, openBrowser as r, isLoopbackHost as s, main as t, pinningHint as u, faviconCandidateSize as v, parseNetstatPorts as w, scrapeService as x, rankFaviconCandidates as y };
 
-//# sourceMappingURL=bin-DgadYsE1.mjs.map
+//# sourceMappingURL=bin-BEqHk5dQ.mjs.map