mixdog 1.3.5 → 1.4.0

package/src/runtime/connectors/gmail-app-password.mjs

@@ -9,11 +9,11 @@
 import { createHash } from 'node:crypto';
 import keychain from '../../lib/keychain-cjs.cjs';
 import { GMAIL_APP_PASSWORD, gmailAddress } from '../shared/connector-catalog.mjs';
-import { accountInstructions } from '../shared/connector-accounts.mjs';
+import { connectorAccountsInstructions } from '../shared/connector-accounts.mjs';
 
 const PROTOCOL_VERSION = '2025-06-18';
-export const GMAIL_IMAP = Object.freeze({ host: 'imap.gmail.com', port: 993, secure: true });
-export const GMAIL_SMTP = Object.freeze({ host: 'smtp.gmail.com', port: 465, secure: true });
+const GMAIL_IMAP = Object.freeze({ host: 'imap.gmail.com', port: 993, secure: true });
+const GMAIL_SMTP = Object.freeze({ host: 'smtp.gmail.com', port: 465, secure: true });
 const TIMEOUTS = { connectionTimeout: 20_000, greetingTimeout: 15_000, socketTimeout: 60_000 };
 const SEARCH_DEFAULT = 10;
 const SEARCH_MAX = 25;
@@ -48,7 +48,7 @@ const MESSAGES = {
 
 /** `GMAIL_APP_PASSWORD_<CODE>: <sentence>` — the code is what Desktop shows
  *  in the user's language. */
-export class GmailAppPasswordError extends Error {
+class GmailAppPasswordError extends Error {
   constructor(code, detail = '') {
     super(`GMAIL_APP_PASSWORD_${code}: ${MESSAGES[code]}${detail ? ` (${detail})` : ''}`);
     this.code = code;
@@ -101,7 +101,7 @@ function gmailError(error, password) {
 }
 
 // ── Clients (tests pass fakes with the same surface) ────────────────────────
-export const gmailClients = {
+const gmailClients = {
   async imap({ email, password }) {
     const { ImapFlow } = await import('imapflow');
     const client = new ImapFlow({
@@ -186,6 +186,64 @@ const addresses = (list) =>
     .map((entry) => (entry?.name ? `${entry.name} <${entry.address || ''}>` : entry?.address || ''))
     .filter(Boolean)
     .join(', ');
+/** The From mailboxes as Gmail parsed them, one entry each; a group shows as
+ *  its name with an empty address (imapflow parseEnvelope). */
+const mailboxes = (list) =>
+  (Array.isArray(list) ? list : []).map((entry) => ({
+    name: String(entry?.name || ''),
+    address: String(entry?.address || ''),
+  }));
+
+const stripComments = (text) => {
+  let out = text;
+  for (let previous = ''; previous !== out; ) {
+    previous = out;
+    out = out.replace(/\([^()]*\)/g, ' ');
+  }
+  return out;
+};
+
+/** Gmail's own verdict on the sender, read from the topmost
+ *  Authentication-Results only, and only when its authserv-id is Gmail's
+ *  (mx.google.com):
+ *  - the receiving MTA prepends the field above the trace fields it adds
+ *    (RFC 8601 §4, §4.1), so the last receiver's copy is the first one;
+ *  - a conforming MTA deletes any copy that arrives bearing its own
+ *    authserv-id (RFC 8601 §5), so a sender cannot pass one off as Gmail's;
+ *  - Gmail directs other mail clients to this field for its verdict (Gmail
+ *    Help, "Check if your Gmail message is authenticated", answer 180707).
+ *  A message no MTA delivered — one appended to the mailbox over IMAP — has
+ *  only the headers its author wrote; that is the account owner's own mail.
+ *  `{ dmarc: { result, from }, dkim: [{ result, domain }] }` (`domain` is a
+ *  signature's d= as header.d reports it, RFC 8601 §2.7.1), or null. */
+function gmailAuthentication(headers) {
+  const unfolded = String(headers || '').replace(/\r?\n[ \t]+/g, ' ');
+  const first = /^authentication-results:(.*)$/im.exec(unfolded)?.[1];
+  if (!first) return null;
+  const [server = '', ...results] = stripComments(first).split(';');
+  if (server.trim().split(/\s+/)[0].toLowerCase() !== 'mx.google.com') return null;
+  const verdict = { dmarc: null, dkim: [] };
+  for (const entry of results) {
+    const method = /^\s*([a-z0-9-]+)\s*=\s*([a-z]+)/i.exec(entry);
+    if (!method) continue;
+    const props = Object.fromEntries(
+      [...entry.matchAll(/([a-z]+\.[a-z]+)\s*=\s*("[^"]*"|[^\s;]+)/gi)].map(([, name, value]) => [
+        name.toLowerCase(),
+        value.replace(/^"|"$/g, '').toLowerCase(),
+      ])
+    );
+    const result = method[2].toLowerCase();
+    if (method[1].toLowerCase() === 'dmarc' && !verdict.dmarc)
+      verdict.dmarc = { result, from: props['header.from'] || '' };
+    // Only the signing domain d= counts toward the From domain (RFC 7489
+    // §3.1.1); the agent identity i= is not an alignment identifier.
+    if (method[1].toLowerCase() === 'dkim' && props['header.d']) {
+      verdict.dkim.push({ result, domain: props['header.d'] });
+    }
+  }
+  return verdict;
+}
+
 const isoDate = (value) => {
   const date = value ? new Date(value) : null;
   return date && !Number.isNaN(date.getTime()) ? date.toISOString() : '';
@@ -214,25 +272,30 @@ const isAttachment = (node) =>
   String(node.type || '').startsWith('message/') ||
   Boolean(node.dispositionParameters?.filename || node.parameters?.name);
 
-/** The text/plain part (else text/html) that is the message's body. */
-function bodyPart(root) {
-  let html = null;
+/** The first text/plain and the first text/html part of the message that are
+ *  not attachments (part numbers), each null without one. */
+function textParts(root) {
+  const found = { plain: null, html: null };
   const walk = (node) => {
-    if (!node || String(node.type || '').startsWith('message/')) return null;
+    if (!node || String(node.type || '').startsWith('message/')) return;
     if (node.childNodes?.length) {
-      for (const child of node.childNodes) {
-        const found = walk(child);
-        if (found) return found;
-      }
-      return null;
+      for (const child of node.childNodes) walk(child);
+      return;
     }
-    if (node.disposition === 'attachment') return null;
+    if (node.disposition === 'attachment') return;
     const part = node.part || '1';
-    if (node.type === 'text/plain') return { part, html: false };
-    if (node.type === 'text/html' && !html) html = { part, html: true };
-    return null;
+    if (node.type === 'text/plain' && !found.plain) found.plain = part;
+    if (node.type === 'text/html' && !found.html) found.html = part;
   };
-  return walk(root) || html;
+  walk(root);
+  return found;
+}
+
+/** The text/plain part (else text/html) that is the message's body. */
+function bodyPart(root) {
+  const { plain, html } = textParts(root);
+  if (plain) return { part: plain, html: false };
+  return html ? { part: html, html: true } : null;
 }
 
 /** Attachments by name, type and (decoded, approximate) size only. */
@@ -264,16 +327,15 @@ const htmlText = (html) =>
     .replace(/ *\n\s*/g, '\n')
     .trim();
 
-/** Up to `maxBytes` of the body text, decoded to UTF-8. */
-async function bodyText(client, uid, structure, maxBytes) {
-  const picked = bodyPart(structure);
-  if (!picked) return '';
-  const download = await client.download(String(uid), picked.part, {
+/** Up to `maxBytes` of part `part`, decoded to UTF-8; `complete` is false when
+ *  the part may go on past them. */
+async function partText(client, uid, part, maxBytes) {
+  const download = await client.download(String(uid), part, {
     uid: true,
     maxBytes,
     chunkSize: Math.min(maxBytes, 65_536),
   });
-  if (!download?.content) return '';
+  if (!download?.content) return { value: '', complete: true };
   const chunks = [];
   let size = 0;
   for await (const chunk of download.content) {
@@ -281,10 +343,63 @@ async function bodyText(client, uid, structure, maxBytes) {
     size += chunk.length;
     if (size >= maxBytes) break;
   }
-  const value = Buffer.concat(chunks).subarray(0, maxBytes).toString('utf8');
+  return { value: Buffer.concat(chunks).subarray(0, maxBytes).toString('utf8'), complete: size < maxBytes };
+}
+
+/** Up to `maxBytes` of the body text, decoded to UTF-8. */
+async function bodyText(client, uid, structure, maxBytes) {
+  const picked = bodyPart(structure);
+  if (!picked) return '';
+  const { value } = await partText(client, uid, picked.part, maxBytes);
   return picked.html ? htmlText(value) : value.trim();
 }
 
+let domModule;
+const loadDom = () => (domModule ||= import('jsdom'));
+
+/** The targets of an HTML part's hyperlinks (`a` and `area` with href, HTML
+ *  Standard §4.6 Links) as the HTML parser reads the attribute, character
+ *  references decoded. A tag the download cut off is no element (HTML
+ *  tokenization: the eof-in-tag error emits no tag). */
+async function htmlLinks(html) {
+  if (!html) return [];
+  const { JSDOM } = await loadDom();
+  const dom = new JSDOM(html);
+  try {
+    return [...dom.window.document.querySelectorAll('a[href], area[href]')].map((node) => node.getAttribute('href'));
+  } finally {
+    dom.window.close();
+  }
+}
+
+// An absolute http(s) URI in plain text as RFC 3986 spells one: the scheme,
+// then a run of URI characters — unreserved, reserved or percent-encoded
+// (§2.1-§2.3). Whitespace, quotes and angle brackets are no URI characters,
+// so they end it (Appendix C).
+const TEXT_URI = /https?:\/\/(?:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=]|%[0-9A-Fa-f]{2})+/gi;
+
+const isWebUrl = (value) => {
+  try {
+    return ['http:', 'https:'].includes(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+};
+
+/** The message's link targets, exactly as written: the hyperlinks of its
+ *  HTML part, then the URIs of its text part (one the download cut off is
+ *  left out). Absolute http(s) only, each once. */
+function messageLinks(plain, hrefs) {
+  const links = [...hrefs];
+  if (plain) {
+    for (const match of plain.value.matchAll(TEXT_URI)) {
+      if (!plain.complete && match.index + match[0].length === plain.value.length) continue;
+      links.push(match[0]);
+    }
+  }
+  return [...new Set(links.filter((link) => typeof link === 'string' && isWebUrl(link)))];
+}
+
 const references = (headers) =>
   String(headers || '')
     .replace(/\r?\n[ \t]+/g, ' ')
@@ -317,7 +432,9 @@ const LABEL_MAX = 225;
 
 /** The distinct message ids of `args.ids` (an array, or one id). */
 function messageIds(args) {
-  const raw = Array.isArray(args.ids) ? args.ids : args.ids == null ? [] : [args.ids];
+  let raw = [];
+  if (Array.isArray(args.ids)) raw = args.ids;
+  else if (args.ids != null) raw = [args.ids];
   const ids = [...new Set(raw.map((id) => text(id)))];
   if (!ids.length || ids.some((id) => !id)) throw new ToolInputError('ids must list ids from search_emails');
   if (ids.length > MANAGE_MAX) throw new ToolInputError(`At most ${MANAGE_MAX} emails per call; got ${ids.length}.`);
@@ -519,7 +636,8 @@ const TOOLS = [
   },
   {
     name: 'read_email',
-    description: 'Read one email by its id from search_emails: headers, text body, and attachment names and sizes.',
+    description:
+      'Read one email by its id from search_emails: headers, text body, link targets, and attachment names and sizes.',
     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
     annotations: { readOnlyHint: true, openWorldHint: true },
     async run(ctx, args) {
@@ -530,22 +648,38 @@ const TOOLS = [
         const [message] = uid
           ? await client.fetchAll(
               String(uid),
-              { uid: true, envelope: true, internalDate: true, bodyStructure: true, threadId: true },
+              {
+                uid: true,
+                envelope: true,
+                internalDate: true,
+                bodyStructure: true,
+                threadId: true,
+                headers: ['authentication-results'],
+              },
               { uid: true }
             )
           : [];
         if (!message) throw new ToolInputError(`No email with id ${id}.`);
         const { envelope = {} } = message;
-        const body = await bodyText(client, message.uid, message.bodyStructure, READ_BYTES);
+        const parts = textParts(message.bodyStructure);
+        const plain = parts.plain ? await partText(client, message.uid, parts.plain, READ_BYTES) : null;
+        const html = parts.html ? await partText(client, message.uid, parts.html, READ_BYTES) : null;
+        let body = '';
+        if (plain) body = plain.value.trim();
+        else if (html) body = htmlText(html.value);
+        const links = messageLinks(plain, await htmlLinks(html?.value));
         const head = {
           id: message.emailId || id,
           threadId: message.threadId,
           messageId: envelope.messageId,
           from: addresses(envelope.from),
+          fromAddresses: mailboxes(envelope.from),
+          authentication: gmailAuthentication(message.headers),
           to: addresses(envelope.to),
           cc: addresses(envelope.cc) || undefined,
           date: isoDate(envelope.date || message.internalDate),
           subject: text(envelope.subject),
+          links,
           attachments: attachmentsOf(message.bodyStructure),
         };
         const clipped = body.length > READ_CHARS ? `${body.slice(0, READ_CHARS)}\n[truncated]` : body;
@@ -588,6 +722,12 @@ const TOOLS = [
   ...MANAGE_TOOLS,
 ];
 
+/** The tool definitions (name, description, schema, annotations) the server
+ *  lists; with `hidden`, also the ones only the approval gate calls. */
+export function gmailAppPasswordTools({ hidden = false } = {}) {
+  return TOOLS.filter((tool) => hidden || !tool.hidden).map(({ run, hidden: _hidden, ...tool }) => tool);
+}
+
 // ── The MCP server at the reserved address ──────────────────────────────────
 const GMAIL_HOST = new URL(GMAIL_APP_PASSWORD.url).host;
 
@@ -616,18 +756,11 @@ async function rpc(session, message) {
       protocolVersion: text(params?.protocolVersion) || PROTOCOL_VERSION,
       capabilities: { tools: { listChanged: false } },
       serverInfo: { name: 'mixdog-gmail-app-password', version: '1.0.0' },
-      instructions: accountInstructions('Gmail', session.email),
+      instructions: connectorAccountsInstructions([{ email: session.email }]),
     });
   }
   if (method === 'ping') return reply({});
-  if (method === 'tools/list') {
-    return reply({
-      tools: TOOLS.filter((tool) => !tool.hidden).map(({ run, hidden, ...tool }) => ({
-        ...tool,
-        description: `${tool.description} (Gmail account: ${session.email})`,
-      })),
-    });
-  }
+  if (method === 'tools/list') return reply({ tools: gmailAppPasswordTools() });
   if (method === 'tools/call') {
     const tool = TOOLS.find((candidate) => candidate.name === params?.name);
     if (!tool) return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${params?.name}` } };

package/src/runtime/connectors/google-mcp.mjs

@@ -9,7 +9,7 @@
 // live in the keychain, and each MCP request carries the access token, which
 // this server spends on the Gmail / Calendar / Drive REST APIs.
 
-import { accountInstructions } from '../shared/connector-accounts.mjs';
+import { connectorAccountsInstructions } from '../shared/connector-accounts.mjs';
 
 const PROTOCOL_VERSION = '2025-06-18';
 const ORIGIN_SUFFIX = '.mixdog.invalid';
@@ -329,6 +329,12 @@ const SERVICES = {
   drive: { name: 'Google Drive', tools: DRIVE_TOOLS },
 };
 
+/** The tool definitions (name, description, schema, annotations) of built-in
+ *  Google service `service` (`gmail`, `calendar`, `drive`). */
+export function googleMcpTools(service) {
+  return (SERVICES[service]?.tools || []).map(({ run, ...tool }) => tool);
+}
+
 /** The reserved MCP address of built-in Google service `service`. */
 export function googleMcpUrl(service) {
   return `https://${service}${ORIGIN_SUFFIX}/mcp`;
@@ -367,20 +373,12 @@ async function rpc(service, token, message) {
       protocolVersion: text(params?.protocolVersion) || PROTOCOL_VERSION,
       capabilities: { tools: { listChanged: false } },
       serverInfo: { name: `mixdog-${service.key}`, version: '1.0.0' },
-      instructions: accountInstructions(service.name, info.email),
+      // The one account this sign-in is (the connector's accounts server reads it back).
+      instructions: connectorAccountsInstructions([{ email: info.email }]),
     });
   }
   if (method === 'ping') return reply({});
-  if (method === 'tools/list') {
-    // Several accounts of one service are separate servers: each tool says whose it is.
-    const { email } = await tokenInfo(token).catch(() => ({ email: '' }));
-    return reply({
-      tools: service.tools.map(({ run, ...tool }) => ({
-        ...tool,
-        ...(email ? { description: `${tool.description} (${service.name} account: ${email})` } : {}),
-      })),
-    });
-  }
+  if (method === 'tools/list') return reply({ tools: googleMcpTools(service.key) });
   if (method === 'tools/call') {
     const tool = service.tools.find((candidate) => candidate.name === params?.name);
     if (!tool) return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${params?.name}` } };

package/src/runtime/memory/lib/pg/adapter.mjs

@@ -91,6 +91,7 @@ function installPoolErrorHandler(pool, label, { onConnectionLoss } = {}) {
 
 import { resolve } from 'node:path';
 import { ensurePgInstance as supervisorEnsure, stopOwnedPgForShutdown } from './supervisor.mjs';
+import { createSharedAbortable } from '../../../shared/abort-race.mjs';
 
 export { installOwnedPgExitStop, pgClusterExists } from './supervisor.mjs';
 
@@ -195,7 +196,7 @@ export function pendingDurablePgOps() {
  * Wait, bounded, until no durable-schema operation is in flight (including
  * ones issued while waiting). Resolves true when drained, false at the bound.
  */
-export async function drainDurablePgOps({ timeoutMs = 0 } = {}) {
+async function drainDurablePgOps({ timeoutMs = 0 } = {}) {
   const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
   while (_durableInFlight.size > 0) {
     const remaining = deadline - Date.now();
@@ -488,78 +489,84 @@ export async function ensurePgInstance(dataDir, opts = {}) {
   const key = instanceKey(dataDir, schema);
 
   if (instances.has(key)) return instances.get(key);
-  if (opening.has(key)) return opening.get(key);
-
-  const promise = (async () => {
-    // 1. Let supervisor-pg own PG startup and health-checking.
-    //    Returns { host, port, runtimeDir, pgdataDir }.
-    const { host, port, runtimeDir, pgdataDir } = await supervisorEnsure(dataDir);
-
-    // 2. Connect via node-postgres; auto-create the mixdog database if absent.
-    const { default: pg } = await import('pg');
-
-    const PG_USER = 'postgres';
-    const PG_DB = 'mixdog';
-
-    const adminPool = new pg.Pool({
-      host,
-      port,
-      user: PG_USER,
-      database: 'postgres',
-      password: '',
-      max: 1,
-      idleTimeoutMillis: 5_000,
-    });
-    installPoolErrorHandler(adminPool, 'admin-pool');
-    try {
-      // CREATE DATABASE cannot run inside a transaction, so guard the
-      // check-then-create with a session-level advisory lock held on a single
-      // dedicated client. Concurrent first-boot workers block on the same
-      // cluster-global key here and only one issues the CREATE; the rest see
-      // the row present after the holder releases. Released in finally.
-      await withClusterAdvisoryLock(adminPool, ADVISORY_OBJID_CREATE_DB, 'create-db', async (adminClient) => {
-        const r = await adminClient.query(`SELECT 1 FROM pg_database WHERE datname = $1`, [PG_DB]);
-        if (r.rows.length === 0) {
-          await adminClient.query(`CREATE DATABASE ${PG_DB}`);
-          __mixdogMemoryLog(`[pg-adapter] created database ${PG_DB}\n`);
-        }
+  // `opts.signal` withdraws this caller; the shared open is cancelled once
+  // every caller has (createSharedAbortable).
+  if (opening.has(key)) return opening.get(key).join(opts.signal);
+
+  const shared = createSharedAbortable(
+    async (signal) => {
+      // 1. Let supervisor-pg own PG startup and health-checking.
+      //    Returns { host, port, runtimeDir, pgdataDir }.
+      const { host, port, runtimeDir, pgdataDir } = await supervisorEnsure(dataDir, { signal });
+      signal.throwIfAborted();
+
+      // 2. Connect via node-postgres; auto-create the mixdog database if absent.
+      const { default: pg } = await import('pg');
+
+      const PG_USER = 'postgres';
+      const PG_DB = 'mixdog';
+
+      const adminPool = new pg.Pool({
+        host,
+        port,
+        user: PG_USER,
+        database: 'postgres',
+        password: '',
+        max: 1,
+        idleTimeoutMillis: 5_000,
       });
-    } finally {
-      await adminPool.end();
-    }
+      installPoolErrorHandler(adminPool, 'admin-pool');
+      try {
+        // CREATE DATABASE cannot run inside a transaction, so guard the
+        // check-then-create with a session-level advisory lock held on a single
+        // dedicated client. Concurrent first-boot workers block on the same
+        // cluster-global key here and only one issues the CREATE; the rest see
+        // the row present after the holder releases. Released in finally.
+        await withClusterAdvisoryLock(adminPool, ADVISORY_OBJID_CREATE_DB, 'create-db', async (adminClient) => {
+          const r = await adminClient.query(`SELECT 1 FROM pg_database WHERE datname = $1`, [PG_DB]);
+          if (r.rows.length === 0) {
+            await adminClient.query(`CREATE DATABASE ${PG_DB}`);
+            __mixdogMemoryLog(`[pg-adapter] created database ${PG_DB}\n`);
+          }
+        });
+      } finally {
+        await adminPool.end();
+      }
 
-    // 3. Production pool.
-    const pgPool = new pg.Pool({
-      host,
-      port,
-      user: PG_USER,
-      database: PG_DB,
-      password: '',
-      max: 5,
-      idleTimeoutMillis: 30_000,
-      connectionTimeoutMillis: 10_000,
-    });
-    installPoolErrorHandler(pgPool, `pool:${schema}`, {
-      onConnectionLoss: () => _recoverPgConnection(dataDir, schema),
-    });
-
-    // 4. Bootstrap extensions + schemas once (idempotent).
-    await bootstrapInstance(pgPool, resolve(dataDir));
-
-    // 5. Build the compat db shim.
-    const db = makeCompatDb(pgPool, schema, dataDir);
-
-    const result = { db, pool: pgPool, host, port, runtimeDir, pgdataDir };
-    instances.set(key, result);
-    return result;
-  })();
+      // 3. Production pool.
+      const pgPool = new pg.Pool({
+        host,
+        port,
+        user: PG_USER,
+        database: PG_DB,
+        password: '',
+        max: 5,
+        idleTimeoutMillis: 30_000,
+        connectionTimeoutMillis: 10_000,
+      });
+      installPoolErrorHandler(pgPool, `pool:${schema}`, {
+        onConnectionLoss: () => _recoverPgConnection(dataDir, schema),
+      });
 
-  opening.set(key, promise);
-  try {
-    return await promise;
-  } finally {
-    opening.delete(key);
-  }
+      // 4. Bootstrap extensions + schemas once (idempotent).
+      await bootstrapInstance(pgPool, resolve(dataDir));
+
+      // 5. Build the compat db shim.
+      const db = makeCompatDb(pgPool, schema, dataDir);
+
+      const result = { db, pool: pgPool, host, port, runtimeDir, pgdataDir };
+      instances.set(key, result);
+      return result;
+    },
+    {
+      onSettled: () => {
+        if (opening.get(key) === shared) opening.delete(key);
+      },
+    }
+  );
+
+  opening.set(key, shared);
+  return shared.join(opts.signal);
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/memory/lib/pg/supervisor.mjs

@@ -30,6 +30,7 @@ import {
 import { withFileLockSync } from '../../../shared/atomic-file.mjs';
 import { isPidAlive } from '../../../shared/pid-liveness.mjs';
 import { envFlag } from '../../../shared/env.mjs';
+import { createSharedAbortable } from '../../../shared/abort-race.mjs';
 import { ensurePrivateRuntimeRoot, resolveRuntimeRoot } from '../../../shared/runtime-root.mjs';
 
 let _pgProc = null;
@@ -51,7 +52,7 @@ async function _getPgProc() {
 /** @type {{ port: number, pgdata: string, runtimeDir: string, proc: unknown } | null} */
 let _live = null;
 /** Dedup: one ensure coroutine at a time. */
-let _ensureInFlight = null;
+let _ensureShared = null;
 /** Per-process flag — postgresql.conf reconcile attempted once per supervisor. */
 let _v2ReconcileTried = false;
 /** Set by stopOwnedPgForShutdown: this process is exiting, no further ensure. */
@@ -542,7 +543,7 @@ async function tryReusePgInstance({ pgdata, runtimeDir, healthcheckPg, source =
   return null;
 }
 
-// ── Internal: full ensure logic (runs exclusively via _ensureInFlight) ────────
+// ── Internal: full ensure logic (runs exclusively via _ensureShared) ──────────
 
 function _pgdataDir(dataDir) {
   return join(dataDir, 'pgdata');
@@ -555,13 +556,15 @@ export function pgClusterExists(dataDir) {
   return existsSync(join(_pgdataDir(dataDir), 'PG_VERSION'));
 }
 
-async function _doEnsure(dataDir) {
+async function _doEnsure(dataDir, signal) {
   const { healthcheckPg } = await _getPgProc();
   const pgdata = _pgdataDir(dataDir);
 
   // Resolve runtimeDir via runtime-fetcher (cache-hits immediately when already downloaded).
   const { ensureRuntime } = await import('../runtime-fetcher.mjs');
-  const { runtimeDir } = await ensureRuntime(dataDir);
+  const { runtimeDir } = await ensureRuntime(dataDir, { signal });
+  // Cancelled while installing: start no cluster for callers that are gone.
+  signal.throwIfAborted();
 
   // One-shot v2 conf reconcile — idempotent. Covers attach paths (in-process
   // fast path / cross-process active-instance reuse) where startPg is never
@@ -713,10 +716,15 @@ async function _doEnsure(dataDir) {
  * Concurrent calls are deduplicated — exactly one spawn/recover sequence runs
  * at a time; additional callers await the same promise.
  *
+ * `signal` (optional) withdraws this caller: the shared ensure is cancelled
+ * (its runtime install included) only once every caller has withdrawn and
+ * none joined without a signal (createSharedAbortable).
+ *
  * @param {string} dataDir  Mixdog data directory.
+ * @param {{ signal?: AbortSignal }} [opts]
  * @returns {Promise<{ host: string, port: number, runtimeDir: string, pgdataDir: string }>}
  */
-export function ensurePgInstance(dataDir) {
+export function ensurePgInstance(dataDir, { signal = null } = {}) {
   // Once this process began stopping the cluster it owns, nothing may start
   // or re-attach one: a late connection-loss recovery would otherwise bring a
   // postmaster back up right after the stop and leave it running past exit.
@@ -727,12 +735,15 @@ export function ensurePgInstance(dataDir) {
   // in-process fast path — so this is the one place the sweep cannot be
   // skipped. Latched internally, so repeated calls schedule it only once.
   scheduleOrphanTempPostmasterSweep();
-  if (!_ensureInFlight) {
-    _ensureInFlight = _doEnsure(dataDir).finally(() => {
-      _ensureInFlight = null;
+  if (!_ensureShared) {
+    const shared = createSharedAbortable((sharedSignal) => _doEnsure(dataDir, sharedSignal), {
+      onSettled: () => {
+        if (_ensureShared === shared) _ensureShared = null;
+      },
     });
+    _ensureShared = shared;
   }
-  return _ensureInFlight;
+  return _ensureShared.join(signal);
 }
 
 /**
@@ -779,7 +790,7 @@ export async function stopPgForShutdown() {
     return;
   }
   const snap = _live;
-  _ensureInFlight = null;
+  _ensureShared = null;
   try {
     const { stopPg } = await _getPgProc();
     await stopPg({ runtimeDir: snap.runtimeDir, pgdataDir: snap.pgdata });
@@ -865,10 +876,11 @@ export async function stopOwnedPgForShutdown({ timeoutMs = 6_000 } = {}) {
   // publishes its cluster only when it settles; stopping before that would
   // miss the postmaster it is about to own. Bounded: a cold first start can
   // be a download.
-  if (_ensureInFlight) {
+  const inFlight = _ensureShared?.promise;
+  if (inFlight) {
     let timer = null;
     await Promise.race([
-      _ensureInFlight.catch(() => {}),
+      inFlight.catch(() => {}),
       new Promise((resolveWait) => {
         timer = setTimeout(resolveWait, timeoutMs);
         timer.unref?.();