mixdog 1.2.2 → 1.2.4

package/src/runtime/media/lanes.mjs

@@ -8,6 +8,7 @@
  * an unauthenticated lane fails closed.
  */
 import { hasAgentApiKey } from '../shared/provider-api-key.mjs';
+import { ACCOUNT_PROVIDERS } from '../shared/provider-accounts.mjs';
 // Credential probes are file-level checks: the catalog must not drag the whole
 // provider graph in just to render lane availability.
 import {
@@ -64,6 +65,7 @@ const LANES = Object.freeze([
     image: Object.freeze({
       controls: Object.freeze({
         maxReferences: 5,
+        background: Object.freeze(['auto', 'transparent', 'opaque']),
       }),
     }),
   }),
@@ -100,6 +102,13 @@ const LANES = Object.freeze([
 
 const LANE_BY_ID = new Map(LANES.map((lane) => [lane.id, lane]));
 
+/** The provider whose connected accounts a lane can generate through, or ''
+ *  for a lane that authenticates with a single API key. */
+export function mediaLaneAccountProvider(laneId) {
+  const provider = LANE_BY_ID.get(String(laneId || '').trim())?.auth.provider;
+  return ACCOUNT_PROVIDERS.includes(provider) ? provider : '';
+}
+
 const OAUTH_PROBES = Object.freeze({
   'grok-oauth': hasGrokOAuthCredentials,
   'openai-oauth': hasOpenAIOAuthCredentials,
@@ -143,6 +152,9 @@ export function createMediaLaneCatalog({ loadModels = loadMediaModels, authentic
       authType: lane.auth.type,
       authProvider: lane.auth.provider,
       authenticated: signedIn,
+      // What the lane can generate once signed in; `kinds` lists only what its
+      // live catalog offers right now.
+      supportedKinds: MEDIA_KINDS.filter((kind) => lane[kind]),
       kinds: [],
       image: null,
       video: null,

package/src/runtime/media/tool-defs.mjs

@@ -31,7 +31,7 @@ export const TOOL_DEFS = [
         lane: {
           type: 'string',
           description:
-            'Lane id from list; omitted = the lane the user last chose for the kind (Studio selection or last generation), else the first signed-in lane.',
+            'Lane id from list; pass it when the user names a source. Omitted = the lane the user last chose for the kind, else the default signed-in lane.',
         },
         model: {
           type: 'string',
@@ -44,10 +44,21 @@ export const TOOL_DEFS = [
           description:
             'generate: output file (png/jpg/mp4); relative to the project. status: copy a finished asset here.',
         },
-        aspect: { type: 'string', description: 'Aspect ratio, e.g. 16:9, 9:16, 1:1; must be one the model lists.' },
-        resolution: { type: 'string', description: 'Model resolution token from list (1k, 2k, 720p, 1080p).' },
+        aspect: {
+          type: 'string',
+          description: 'Aspect ratio, e.g. 16:9, 9:16, 1:1; only when the model lists aspectRatio, else omit.',
+        },
+        resolution: {
+          type: 'string',
+          description: 'Resolution token (1k, 2k, 720p, 1080p); only when the model lists it, else omit.',
+        },
         duration: { type: 'number', description: "video: seconds, within the model's listed durations." },
-        quality: { type: 'string', description: 'Quality token when the model lists one.' },
+        quality: { type: 'string', description: 'Quality token; only when the model lists one, else omit.' },
+        background: {
+          type: 'string',
+          enum: ['auto', 'transparent', 'opaque'],
+          description: 'image: transparent for real alpha; only when the model lists background, else omit.',
+        },
         references: {
           type: 'array',
           items: { type: 'string' },

package/src/runtime/media/tool.mjs

@@ -8,6 +8,7 @@ import { MEDIA_ACTIONS, MEDIA_KINDS } from './tool-defs.mjs';
 import { clean } from '../shared/clean.mjs';
 
 const POLL_MS = 750;
+const DEFAULT_LANE = 'openai-oauth';
 const TIMEOUT_MS = Object.freeze({ image: 180_000, video: 900_000 });
 // OpenAI's image lane takes pixel sizes, not ratios; the placement still speaks in ratios.
 const OPENAI_SIZE = Object.freeze({
@@ -36,6 +37,7 @@ async function mediaGraph(deps) {
     jobs: await import('./jobs.mjs'),
     store: await import('./store.mjs'),
     defaults: await import('./defaults.mjs'),
+    accounts: await import('../shared/provider-auth-binding.mjs'),
   };
   return graph;
 }
@@ -130,8 +132,9 @@ export function listMediaCatalog(lanes, { kind = '', model = '' } = {}, remember
 
 /**
  * Lane for a generate: the requested one, else the lane the user last chose
- * for this kind (Studio selection or last generation), else the first
- * signed-in lane. `laneSource` tells the caller which of the three applied.
+ * for this kind (Studio selection or last generation), else the signed-in
+ * ChatGPT-subscription lane, else the first signed-in lane. `laneSource` is
+ * `first` for either default.
  */
 function pickLane(lanes, kind, requested, remembered = null) {
   const available = lanes.filter((lane) => lane.authenticated && lane.kinds.includes(kind));
@@ -153,9 +156,8 @@ function pickLane(lanes, kind, requested, remembered = null) {
     );
   }
   const rememberedLane = remembered?.lane ? available.find((entry) => entry.id === remembered.lane) : null;
-  return rememberedLane
-    ? { lane: rememberedLane, laneSource: 'remembered' }
-    : { lane: available[0], laneSource: 'first' };
+  if (rememberedLane) return { lane: rememberedLane, laneSource: 'remembered' };
+  return { lane: available.find((entry) => entry.id === DEFAULT_LANE) || available[0], laneSource: 'first' };
 }
 
 function readRemembered(defaults, kind) {
@@ -166,6 +168,14 @@ function readRemembered(defaults, kind) {
   }
 }
 
+function readPin(defaults, kind) {
+  try {
+    return defaults?.getMediaPin?.(kind) || null;
+  } catch {
+    return null;
+  }
+}
+
 function allowed(controls, key) {
   const list = controls?.[key];
   return Array.isArray(list) && list.length ? list : null;
@@ -185,9 +195,13 @@ export function buildOptions(
   lane,
   kind,
   controls,
-  { aspect = '', resolution = '', duration = null, quality = '' } = {}
+  { aspect = '', resolution = '', duration = null, quality = '', background = '' } = {}
 ) {
   const options = {};
+  if (background) {
+    validateChoice(controls, 'background', background, 'background');
+    if (background !== 'auto') options.background = background;
+  }
   if (lane.id === 'openai-oauth') {
     if (!allowed(controls, 'size')) {
       if ([aspect, resolution, quality].some((value) => value && value !== 'auto')) {
@@ -291,9 +305,21 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
   const requestedPath = clean(args.path);
   if (!requestedPath) throw new MediaToolError('generate requires path: where to write the file');
   const target = fullPath(requestedPath, cwd);
-  const { lanes, jobs, store, defaults } = await mediaGraph(deps);
-  const remembered = readRemembered(defaults, kind);
-  const { lane, laneSource } = pickLane(await lanes.listMediaLanes(), kind, clean(args.lane), remembered);
+  const { lanes, jobs, store, defaults, accounts } = await mediaGraph(deps);
+  // A generator the chat names (lane or model) wins for this call; otherwise
+  // the pinned default for the kind applies, and with none the remembered
+  // choice / ordered default. A pin never falls back: its lane, model and
+  // account errors surface as they are.
+  const pin = clean(args.lane) || clean(args.model) ? null : readPin(defaults, kind);
+  const remembered = pin ? null : readRemembered(defaults, kind);
+  const accountProvider = pin?.account ? lanes.mediaLaneAccountProvider?.(pin.lane) || '' : '';
+  const listLanes = () =>
+    accountProvider
+      ? accounts.withProviderAccount(accountProvider, pin.account, () => lanes.listMediaLanes())
+      : lanes.listMediaLanes();
+  const picked = pickLane(await listLanes(), kind, pin ? pin.lane : clean(args.lane), remembered);
+  const { lane } = picked;
+  const laneSource = pin ? 'pinned' : picked.laneSource;
   const spec = lane[kind];
   // The remembered model only applies on the remembered lane and only while
   // that lane still lists it; otherwise the lane default is the safe choice.
@@ -301,7 +327,7 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
     laneSource === 'remembered' && remembered.model && spec.models.some((entry) => entry.id === remembered.model)
       ? remembered.model
       : '';
-  const modelId = clean(args.model) || rememberedModel || spec.defaultModel;
+  const modelId = clean(args.model) || pin?.model || rememberedModel || spec.defaultModel;
   const model = modelControls(lane, kind, modelId);
   if (!model)
     throw new MediaToolError(`model "${modelId}" is not available on ${lane.id} for ${kind}`, {
@@ -312,6 +338,7 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
     resolution: clean(args.resolution),
     duration: args.duration ?? null,
     quality: clean(args.quality),
+    background: clean(args.background),
   });
   const references = await readReferences(args.references, cwd, model.controls);
   const started = await jobs.startMediaJob({
@@ -323,6 +350,7 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
     references,
     sessionId,
     sourceType,
+    ...(accountProvider ? { account: pin.account } : {}),
   });
   const base = { lane: lane.id, model: modelId, laneSource, options, referenceCount: references.length, prompt };
   if (args.wait === false) {
@@ -396,11 +424,12 @@ export async function executeMediaTool(
         ...listMediaCatalog(
           await lanes.listMediaLanes(),
           { kind, model: clean(args.model) },
-          readRemembered(defaults, kind)
+          readPin(defaults, kind) || readRemembered(defaults, kind)
         ),
       });
     }
-    if (action === 'generate') return mediaToolResult(await generate(args, { cwd, signal, deps, sessionId, sourceType }));
+    if (action === 'generate')
+      return mediaToolResult(await generate(args, { cwd, signal, deps, sessionId, sourceType }));
     if (action === 'status') return mediaToolResult(await status(args, { cwd, deps }));
     return mediaToolResult(await cancel(args, { deps }));
   } catch (error) {

package/src/runtime/media/upstream-error.mjs

@@ -9,20 +9,34 @@
 import { mediaError } from './lanes.mjs';
 
 const CREDIT_HINTS = /credit|spending limit|billing|quota|insufficient|payment/i;
+// Subscription usage caps (ChatGPT plan windows), as opposed to short-lived
+// rate limiting: retrying in a moment does not help until the window resets.
+const USAGE_LIMIT = /usage_?limit/i;
 
-function reason(text) {
+function parseJson(text) {
   try {
-    const parsed = JSON.parse(text);
-    const message = parsed?.error?.message || parsed?.error || parsed?.message;
-    return typeof message === 'string' ? message : '';
+    return JSON.parse(text);
   } catch {
-    return '';
+    return null;
   }
 }
 
+function reason(text) {
+  const parsed = parseJson(text);
+  const message = parsed?.error?.message || parsed?.error || parsed?.message;
+  return typeof message === 'string' ? message : '';
+}
+
+// Raw bodies are only echoed when they are short plain text; HTML error pages
+// and other markup never reach the Studio.
+function rawDetail(text) {
+  const raw = String(text || '').trim();
+  return raw && !raw.startsWith('<') ? raw.slice(0, 300) : '';
+}
+
 /** Build the error a lane throws for a non-OK upstream response. */
 export function upstreamError(label, status, text) {
-  const detail = reason(text) || String(text || '').slice(0, 300);
+  const detail = reason(text) || rawDetail(text);
   if (status === 401 || status === 403) {
     if (CREDIT_HINTS.test(detail)) {
       return mediaError(`${label}: account has no usable balance — ${detail}`, 'MEDIA_BILLING_BLOCKED', status);
@@ -41,3 +55,55 @@ export function upstreamError(label, status, text) {
   }
   return mediaError(`${label} failed (${status})${detail ? `: ${detail}` : ''}`, 'MEDIA_UPSTREAM_FAILED', status);
 }
+
+const header = (headers, name) => String(headers?.get?.(name) || '').trim();
+const epochSeconds = (value) => (Number.isFinite(Number(value)) && Number(value) > 0 ? Math.trunc(Number(value)) : 0);
+
+// Latest reset among the exhausted windows advertised in the rate-limit
+// headers. The family is named after the active limit, with the plain codex
+// family as the fallback the backend also sends.
+function headerResetAt(headers, limitId) {
+  const families = new Set([limitId && `x-${limitId.toLowerCase().replace(/_/g, '-')}`, 'x-codex'].filter(Boolean));
+  let latest = 0;
+  for (const family of families) {
+    for (const window of ['primary', 'secondary']) {
+      const used = Number(header(headers, `${family}-${window}-used-percent`));
+      const resetAt = epochSeconds(header(headers, `${family}-${window}-reset-at`));
+      if (used >= 100 && resetAt > latest) latest = resetAt;
+    }
+  }
+  return latest || null;
+}
+
+/**
+ * Recognize a subscription usage-limit failure. `error` is the upstream error
+ * object (`{ type, code, resets_at }`), from an HTTP body or a stream event.
+ * Returns `{ limitId, resetsAt }` (epoch seconds or null), or null when the
+ * failure is something else.
+ */
+export function usageLimitInfo(error, headers) {
+  const kinds = [error?.type, error?.code, header(headers, 'x-codex-rate-limit-reached-type')];
+  if (!kinds.some((kind) => typeof kind === 'string' && USAGE_LIMIT.test(kind))) return null;
+  const limitId = header(headers, 'x-codex-active-limit') || String(error?.limit_id || error?.metered_feature || '');
+  return { limitId, resetsAt: epochSeconds(error?.resets_at) || headerResetAt(headers, limitId) };
+}
+
+/** usageLimitInfo for a non-OK HTTP response; only 429s are usage limits. */
+export function usageLimitFromResponse(status, text, headers) {
+  if (status !== 429) return null;
+  const parsed = parseJson(text);
+  return usageLimitInfo(parsed?.error && typeof parsed.error === 'object' ? parsed.error : parsed, headers);
+}
+
+function formatResetAt(seconds) {
+  return `${new Date(seconds * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+
+/** The error a lane throws when the subscription's usage window is exhausted. */
+export function usageLimitError(label, { limitId = '', resetsAt = null } = {}) {
+  const what = /image/i.test(limitId) ? 'image generation usage limit reached' : 'usage limit reached';
+  const when = resetsAt ? `resets ${formatResetAt(resetsAt)}` : 'try again after the usage window resets';
+  const err = mediaError(`${label}: ${what} — ${when}`, 'MEDIA_USAGE_LIMIT', 429);
+  if (resetsAt) err.resetsAt = new Date(resetsAt * 1000).toISOString();
+  return err;
+}

package/src/runtime/memory/index.mjs

@@ -532,6 +532,7 @@ const _httpRouter = createHttpRouter({
     _traceDb = v;
   },
   ingestTranscriptFile,
+  forgetTranscripts: _transcriptIngest.forgetTranscripts,
   getTranscriptOffset: (fp) => _transcriptIngest.getOffset(fp),
   parseTsToMs,
   refreshCoreMemoryFile: refreshCoreMemorySnapshot,

package/src/runtime/memory/lib/http-router/ingest-routes.mjs

@@ -15,7 +15,14 @@ const INSERT_ENTRY = `
             RETURNING id
           `;
 
-export function createIngestHandler({ getDb, log, ingestTranscriptFile, getTranscriptOffset, parseTsToMs }) {
+export function createIngestHandler({
+  getDb,
+  log,
+  ingestTranscriptFile,
+  forgetTranscripts,
+  getTranscriptOffset,
+  parseTsToMs,
+}) {
   const entry = async (body, res) => {
     const db = getDb();
     const role = String(body.role ?? 'user');
@@ -89,9 +96,23 @@ export function createIngestHandler({ getDb, log, ingestTranscriptFile, getTrans
     }
   };
 
+  const forgetTranscript = async (body, res) => {
+    const filePaths = body.filePaths;
+    if (!Array.isArray(filePaths) || filePaths.some((filePath) => typeof filePath !== 'string' || !filePath)) {
+      sendJson(res, { error: 'filePaths required' }, 400);
+      return;
+    }
+    try {
+      sendJson(res, { ok: true, removed: await forgetTranscripts(filePaths) });
+    } catch (e) {
+      sendJson(res, { error: e.message }, 500);
+    }
+  };
+
   const routes = {
     '/entry': entry,
     '/ingest-transcript': ingestTranscript,
+    '/transcript/forget': forgetTranscript,
     '/transcript/ingest-sync': ingestSync,
   };
 

package/src/runtime/memory/lib/ingest/transcript-offsets.mjs

@@ -47,6 +47,8 @@ export function createTranscriptOffsets({ loadMeta, persistMeta, log }) {
     set: (transcriptPath, position) => {
       offsets.set(transcriptPath, position);
     },
+    /** Drop one file's read position; true when an entry existed. */
+    forget: (transcriptPath) => offsets.delete(transcriptPath),
     reset: () => {
       offsets = new Map();
     },

package/src/runtime/memory/lib/ingest/transcript-rows.mjs

@@ -69,6 +69,7 @@ export function cwdFromTranscriptPath(fp) {
  *  prefix envelopes, drops synthetic reference-files/compaction/ack/
  *  internal-notification rows). */
 export function transcriptRowFromLine(parsed) {
+  if (parsed.memoryEligible === false) return null;
   const role =
     parsed.message?.role ?? (parsed.type === 'user' || parsed.type === 'assistant' ? parsed.type : undefined);
   if (role !== 'user' && role !== 'assistant') return null;

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

@@ -90,7 +90,9 @@ function installPoolErrorHandler(pool, label, { onConnectionLoss } = {}) {
 //   db.transaction(async tx => …)  → auto BEGIN/COMMIT, ROLLBACK on throw
 
 import { resolve } from 'node:path';
-import { ensurePgInstance as supervisorEnsure } from './supervisor.mjs';
+import { ensurePgInstance as supervisorEnsure, stopOwnedPgForShutdown } from './supervisor.mjs';
+
+export { installOwnedPgExitStop, pgClusterExists } from './supervisor.mjs';
 
 // ---------------------------------------------------------------------------
 // One-shot bootstrap guard — keyed by resolved dataDir (cluster-level, not schema)
@@ -164,6 +166,52 @@ export async function checkedConnect(pgPool, schema) {
   return client;
 }
 
+// ---------------------------------------------------------------------------
+// Durable-operation tracking — a shutdown lets these settle before PG stops
+// ---------------------------------------------------------------------------
+
+/** Schemas holding only data rebuilt from another source of truth: the
+ *  session-search copy (re-ingested from the session files by its backfill)
+ *  and trace diagnostics. Every other schema (scheduler, webhooks, memory)
+ *  holds the only copy, so its in-flight operations are drained first. */
+const DERIVED_SCHEMAS = new Set(['session_search', 'trace']);
+const _durableInFlight = new Set();
+
+function trackDurable(schema, run) {
+  if (DERIVED_SCHEMAS.has(schema)) return run();
+  const op = run();
+  _durableInFlight.add(op);
+  const settle = () => _durableInFlight.delete(op);
+  op.then(settle, settle);
+  return op;
+}
+
+/** In-flight operations on durable schemas right now. */
+export function pendingDurablePgOps() {
+  return _durableInFlight.size;
+}
+
+/**
+ * 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 } = {}) {
+  const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  while (_durableInFlight.size > 0) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    let timer = null;
+    await Promise.race([
+      Promise.allSettled([..._durableInFlight]),
+      new Promise((resolveBound) => {
+        timer = setTimeout(resolveBound, remaining);
+      }),
+    ]);
+    clearTimeout(timer);
+  }
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // native PG db shim
 // ---------------------------------------------------------------------------
@@ -253,6 +301,12 @@ function makeCompatDb(pgPool, schema, dataDir) {
       return currentPool();
     },
   };
+  // Every statement entry point is tracked, so a shutdown can let durable
+  // writes settle before it stops the cluster.
+  const { query, exec, transaction } = db;
+  db.query = (sql, params) => trackDurable(schema, () => query(sql, params));
+  db.exec = (sql) => trackDurable(schema, () => exec(sql));
+  db.transaction = (fn) => trackDurable(schema, () => transaction(fn));
   return db;
 }
 
@@ -522,3 +576,46 @@ export async function closePgInstance(dataDir, opts = {}) {
   } catch {}
   instances.delete(key);
 }
+
+// ---------------------------------------------------------------------------
+// shutdownOwnedPg — process exit: every pool, then the cluster this process owns
+// ---------------------------------------------------------------------------
+
+export const POOL_CLOSE_BOUND_MS = 500;
+
+/**
+ * For a host whose stores start PostgreSQL (the daemon's schedules/webhooks/
+ * session-search): stop the cluster it ensured (supervisor
+ * stopOwnedPgForShutdown, `pg_ctl stop -m fast`) while every pool this process
+ * opened ends alongside — a pool waiting on a checked-out client never holds
+ * the stop back. The stop latches the supervisor first (synchronously), so a
+ * pooled client that sees fast shutdown terminate its backend cannot restart
+ * PG through connection-loss recovery; the pools are dropped from the cache,
+ * and their close is waited on only for a short bound after the stop.
+ */
+export async function shutdownOwnedPg({ timeoutMs, drainMs = 0 } = {}) {
+  // Durable writes still in flight (schedule/webhook state) commit first,
+  // bounded by `drainMs`; derived writes (session search, trace) are not
+  // waited on — their sources rebuild them.
+  if (!(await drainDurablePgOps({ timeoutMs: drainMs }))) {
+    __mixdogMemoryLog(
+      `[pg-adapter] stopping PG with ${_durableInFlight.size} durable operation(s) still in flight after ${drainMs}ms\n`
+    );
+  }
+  const pools = [...instances.values()].map((inst) => inst.pool);
+  instances.clear();
+  const stopping = stopOwnedPgForShutdown({ timeoutMs });
+  const closing = Promise.allSettled(pools.map((pool) => pool.end()));
+  try {
+    return await stopping;
+  } finally {
+    let timer = null;
+    await Promise.race([
+      closing,
+      new Promise((resolveBound) => {
+        timer = setTimeout(resolveBound, POOL_CLOSE_BOUND_MS);
+      }),
+    ]);
+    clearTimeout(timer);
+  }
+}

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

@@ -5,8 +5,11 @@ import { sleep as delay } from '../../../shared/sleep.mjs';
 //
 // Public API:
 //   startPg({ runtimeDir, pgdataDir, port?, logPath? }) → { pid, port }
-//   stopPg({ runtimeDir, pgdataDir })                   → void
+//   stopPg({ runtimeDir, pgdataDir, timeoutMs? })       → void
 //   healthcheckPg({ port, host? })                      → boolean
+//
+// Every child on the start/stop path (initdb, pg_ctl start/reload/status/stop)
+// runs async; only stopPgSync — a process 'exit' hook — may block.
 
 import {
   existsSync,
@@ -24,6 +27,7 @@ import { join } from 'node:path';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { createConnection, createServer } from 'node:net';
 import { isPidAlive } from '../../../shared/pid-liveness.mjs';
+import { runChild } from './run-child.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -201,14 +205,12 @@ function ensureConfV2(pgdataDir) {
 // callers route through this rather than re-implementing the conf/reload pair.
 // Reload-compatible settings apply immediately; postmaster settings such as
 // max_connections apply on the next normal PG start (never restart live work).
-export function reconcileConfV2(runtimeDir, pgdataDir) {
+export async function reconcileConfV2(runtimeDir, pgdataDir) {
   const applied = ensureConfV2(pgdataDir);
   if (!applied) return { applied: false, reloaded: false };
-  const reload = spawnSync(pgBin(runtimeDir, 'pg_ctl'), ['reload', '-D', pgdataDir], {
+  const reload = await runChild(pgBin(runtimeDir, 'pg_ctl'), ['reload', '-D', pgdataDir], {
     env: libEnv(runtimeDir),
-    stdio: 'pipe',
-    timeout: 5_000,
-    windowsHide: true,
+    timeoutMs: 5_000,
   });
   const reloaded = reload.status === 0;
   if (reloaded) {
@@ -238,7 +240,7 @@ async function attachExistingPostmaster({ runtimeDir, pgdataDir, existingWaitMs,
     __mixdogMemoryLog(`[pg-process] attaching to existing PG pid=${existing.pid} port=${existing.port}\n`);
     // Route through the single reconcile entry point so v1 → v2 conf
     // upgrades land on already-running instances without restart.
-    if (v2Applied) reconcileConfV2(runtimeDir, pgdataDir);
+    if (v2Applied) await reconcileConfV2(runtimeDir, pgdataDir);
     return { pid: existing.pid, port: existing.port, attached: true };
   }
   if (existing.state === 'alive-not-ready') {
@@ -259,6 +261,10 @@ async function attachExistingPostmaster({ runtimeDir, pgdataDir, existingWaitMs,
 // default_transaction_isolation: native PG default is read committed.
 // Native PG does not default to serializable; set isolation level explicitly
 // so behaviour is unambiguous across PG major versions.
+// Carries every versioned block ensureConfV2 checks for, so a fresh cluster
+// already holds what later boots expect: none of them rewrites the conf and
+// pg_ctl-reloads it (a postmaster-only setting such as shared_buffers cannot
+// change by reload, and every such reload logged an error).
 function freshClusterConfAppend() {
   return (
     [
@@ -279,7 +285,8 @@ function freshClusterConfAppend() {
     ].join('\n') +
     '\n' +
     buildV2Block() +
-    buildV3Block()
+    buildV3Block() +
+    buildV4Block()
   );
 }
 
@@ -290,14 +297,14 @@ function freshClusterConfAppend() {
  * user profile). Such a share dir is passed through an ASCII junction under
  * %ProgramData% that is removed afterwards.
  */
-export function withInitdbShareDir(runtimeDir, run) {
+export async function withInitdbShareDir(runtimeDir, run) {
   const shareDir = join(runtimeDir, 'share');
   if (process.platform !== 'win32' || /^[\x20-\x7e]*$/.test(shareDir)) return run(null);
   const linkRoot = mkdtempSync(join(process.env.ProgramData, 'mixdog-initdb-'));
   const link = join(linkRoot, 'share');
   try {
     symlinkSync(shareDir, link, 'junction');
-    return run(link);
+    return await run(link);
   } finally {
     // Cleanup must not replace initdb's own result or error. Both removals are
     // non-recursive, so the junction target (the runtime share) is never touched.
@@ -312,11 +319,11 @@ export function withInitdbShareDir(runtimeDir, run) {
 }
 
 /** initdb if pgdata is not yet initialised (no PG_VERSION file). */
-function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
+async function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
   if (existsSync(join(pgdataDir, 'PG_VERSION'))) return;
   __mixdogMemoryLog(`[pg-process] initdb → ${pgdataDir}\n`);
-  const r = withInitdbShareDir(runtimeDir, (shareDir) =>
-    spawnSync(
+  const r = await withInitdbShareDir(runtimeDir, (shareDir) =>
+    runChild(
       pgBin(runtimeDir, 'initdb'),
       [
         '-D',
@@ -329,7 +336,7 @@ function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
         '-U',
         'postgres',
       ],
-      { env, stdio: 'pipe', windowsHide: true }
+      { env }
     )
   );
   if (r.status !== 0) {
@@ -435,12 +442,7 @@ async function startAndWaitReady({ pgctl, startArgs, env, pgdataDir, port }) {
  */
 async function attachRaceWinner({ pgdataDir, pgctl, env, existingWaitMs }) {
   __mixdogMemoryLog(`[pg-process] pg_ctl start: "another server might be running" — probing status\n`);
-  const statusR = spawnSync(pgctl, ['status', '-D', pgdataDir], {
-    env,
-    stdio: 'pipe',
-    timeout: 3_000,
-    windowsHide: true,
-  });
+  const statusR = await runChild(pgctl, ['status', '-D', pgdataDir], { env, timeoutMs: 3_000 });
   __mixdogMemoryLog(
     `[pg-process] pg_ctl status: ${statusR.stdout?.toString() || statusR.stderr?.toString() || 'no output'}\n`
   );
@@ -480,7 +482,7 @@ export async function startPg({
   if (attached) return attached;
 
   const pgctl = pgBin(runtimeDir, 'pg_ctl');
-  initClusterIfNeeded({ runtimeDir, pgdataDir, env });
+  await initClusterIfNeeded({ runtimeDir, pgdataDir, env });
   // PostgreSQL requires a completely empty target on first init. Creating the
   // Spotlight marker before initdb makes every fresh macOS cluster fail with
   // "directory exists but is not empty"; add it only after initialization.
@@ -511,15 +513,18 @@ export async function startPg({
 // stopPg
 // ---------------------------------------------------------------------------
 
-export async function stopPg({ runtimeDir, pgdataDir }) {
+// Bounded graceful stop. `-m fast` rolls back open transactions and
+// disconnects clients; pg_ctl's own wait (-t, whole seconds) and the child
+// timeout share `timeoutMs`, so a wedged stop rejects instead of holding a
+// shutdown sequence open.
+export async function stopPg({ runtimeDir, pgdataDir, timeoutMs = 15_000 }) {
   const pgctl = pgBin(runtimeDir, 'pg_ctl');
   const env = libEnv(runtimeDir);
+  const waitSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
 
-  const r = spawnSync(pgctl, ['stop', '-m', 'fast', '-w', '-D', pgdataDir], {
+  const r = await runChild(pgctl, ['stop', '-m', 'fast', '-w', '-t', String(waitSeconds), '-D', pgdataDir], {
     env,
-    stdio: 'pipe',
-    timeout: 15_000,
-    windowsHide: true,
+    timeoutMs: waitSeconds * 1000 + 1_000,
   });
 
   if (r.status !== 0) {
@@ -662,13 +667,11 @@ async function listPostmasterRows() {
   }
   const stdout = await execFileText('ps', ['-eo', 'pid=,etimes=,args='], { timeout: 15_000 });
   if (stdout === null) return [];
-  return stdout
-    .split(/\r?\n/)
-    .flatMap((line) => {
-      const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.*postgres.*)$/);
-      if (!match) return [];
-      return [{ pid: Number(match[1]), uptimeSec: Number(match[2]), args: match[3] }];
-    });
+  return stdout.split(/\r?\n/).flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.*postgres.*)$/);
+    if (!match) return [];
+    return [{ pid: Number(match[1]), uptimeSec: Number(match[2]), args: match[3] }];
+  });
 }
 
 const PRISTINE_ROOT_PREFIX = 'mixdog-headless-pristine-';