mixdog 0.9.0 → 0.9.2

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

@@ -105,31 +105,50 @@ const _checkedConnect = checkedConnect
 // native PG db shim
 // ---------------------------------------------------------------------------
 
-function makeCompatDb(pgPool, schema) {
+function makeCompatDb(pgPool, schema, dataDir) {
   const db = {
     // query: use pool directly for single-statement queries
     query: async (sql, params) => {
-      const client = await _checkedConnect(pgPool, schema)
-      try {
-        return await client.query(sql, params)
-      } finally {
-        client.release()
-      }
+      return await withPgRetry(dataDir, schema, async (pool) => {
+        const client = await _checkedConnect(pool, schema)
+        try {
+          return await client.query(sql, params)
+        } finally {
+          client.release()
+        }
+      })
     },
 
     // exec: multi-statement SQL (semicolon-separated); single client for session state
     exec: async (sql) => {
-      const client = await _checkedConnect(pgPool, schema)
+      // Not retried: exec runs arbitrary multi-statement SQL where a partial
+      // failure mid-sequence is unobservable from here — replaying the whole
+      // string after recovery risks double-applying already-committed
+      // statements. On ECONNREFUSED, trigger recovery in the background (so
+      // the NEXT call gets a fresh pool) and propagate the original error.
+      const pool = instances.get(`${resolve(dataDir)}|${schema}`)?.pool ?? pgPool
       try {
-        await client.query(sql)
-      } finally {
-        client.release()
+        const client = await _checkedConnect(pool, schema)
+        try {
+          await client.query(sql)
+        } finally {
+          client.release()
+        }
+      } catch (err) {
+        if (err?.code === 'ECONNREFUSED') _recoverPgConnection(dataDir, schema).catch(() => {})
+        throw err
       }
     },
 
     // transaction: check out one client, BEGIN, run callback(tx), COMMIT or ROLLBACK
     transaction: async (fn) => {
-      const client = await _checkedConnect(pgPool, schema)
+      // Not retried — same rationale as exec(): a COMMIT that fails with
+      // ECONNREFUSED leaves the transaction's applied/rolled-back state
+      // unknown to this process; blindly replaying fn() could double-apply
+      // side effects. Recover in the background for the next caller and
+      // propagate the original error immediately.
+      const pool = instances.get(`${resolve(dataDir)}|${schema}`)?.pool ?? pgPool
+      const client = await _checkedConnect(pool, schema)
       try {
         await client.query('BEGIN')
         const tx = {
@@ -141,6 +160,7 @@ function makeCompatDb(pgPool, schema) {
         return result
       } catch (err) {
         try { await client.query('ROLLBACK') } catch {}
+        if (err?.code === 'ECONNREFUSED') _recoverPgConnection(dataDir, schema).catch(() => {})
         throw err
       } finally {
         client.release()
@@ -150,12 +170,116 @@ function makeCompatDb(pgPool, schema) {
     // close: drain pool
     close: () => pgPool.end(),
 
-    // Internal access for callers that need raw pool
-    _pool: pgPool,
+    // Internal access for callers that need raw pool. Getter (not a fixed
+    // field) so callers that hold onto `db` across a recovery cycle (e.g.
+    // trace-store's checkedConnect/pool.connect() call sites) transparently
+    // see the refreshed pool after withPgRetry swaps the cached instance —
+    // otherwise db._pool would keep pointing at the dead pre-recovery pool.
+    get _pool() {
+      return instances.get(`${resolve(dataDir)}|${schema}`)?.pool ?? pgPool
+    },
   }
   return db
 }
 
+// ---------------------------------------------------------------------------
+// Self-healing: pool query fails with ECONNREFUSED (target pg_port down while
+// the server process itself stays alive) → discard the stale pool via
+// closePgInstance and re-run ensurePgInstance so supervisor-pg restarts/
+// re-attaches PG, then retry the failed operation exactly once against the
+// fresh pool.
+//
+// Guards against runaway restart loops:
+//   - _recoverInFlight: at most one recovery coroutine per dataDir at a time;
+//     concurrent callers await the same promise instead of racing restarts.
+//   - _lastRecoverAt / RECOVER_COOLDOWN_MS: after a recovery attempt (success
+//     or failure) further ECONNREFUSED hits within the cooldown window
+//     surface the original error instead of re-triggering PG restart.
+// ---------------------------------------------------------------------------
+
+const RECOVER_COOLDOWN_MS = 15_000
+const _lastRecoverAt = new Map()   // dataDirKey → epoch ms of last recovery attempt
+const _recoverInFlight = new Map() // dataDirKey → Promise<boolean>
+
+function _instanceKeysForDataDir(dataDirKey) {
+  const prefix = `${dataDirKey}|`
+  return Array.from(instances.keys()).filter(k => k.startsWith(prefix))
+}
+
+async function _recoverPgConnection(dataDir, schema) {
+  const dataDirKey = resolve(dataDir)
+  // In-flight check FIRST: a concurrent recovery already running for this
+  // dataDir must be awaited by every caller (even ones arriving inside the
+  // cooldown window that starts once that recovery begins) — otherwise a
+  // caller that lands between the in-flight recovery's start and its cooldown
+  // stamp would see neither in-flight nor cooldown and could trigger a second
+  // redundant restart cycle.
+  if (_recoverInFlight.has(dataDirKey)) return _recoverInFlight.get(dataDirKey)
+  const now = Date.now()
+  const last = _lastRecoverAt.get(dataDirKey) || 0
+  if (now - last < RECOVER_COOLDOWN_MS) {
+    // Cooldown active — do not hammer PG restart on every failing query.
+    return false
+  }
+
+  const p = (async () => {
+    _lastRecoverAt.set(dataDirKey, Date.now())
+    __mixdogMemoryLog(`[pg-adapter] ECONNREFUSED on pool query — recovering PG for dataDir=${dataDirKey}\n`)
+    // memory + trace schemas share one PG cluster/port; discard every cached
+    // pool for this dataDir so a dead-port pool is never reused after restart.
+    // Track every schema whose pool was actually closed here so ALL of them
+    // get re-ensured below (not just the schema of the caller that happened
+    // to trigger this recovery) — otherwise a sibling schema's cached `db`
+    // handle is left pointing at an ended pool (its `_pool` getter falls back
+    // to the stale `pgPool` closure var) and its next query throws a
+    // "Cannot use a pool after calling end" TypeError instead of recovering.
+    const closedSchemas = new Set()
+    for (const key of _instanceKeysForDataDir(dataDirKey)) {
+      const sch = key.slice(dataDirKey.length + 1)
+      try { await closePgInstance(dataDir, { schema: sch }) } catch {}
+      closedSchemas.add(sch)
+    }
+    closedSchemas.add(schema) // the triggering schema, even if it had no cached instance yet
+    try {
+      for (const sch of closedSchemas) {
+        await ensurePgInstance(dataDir, { schema: sch })
+      }
+      __mixdogMemoryLog(`[pg-adapter] PG reconnect recovery complete for dataDir=${dataDirKey}\n`)
+      return true
+    } catch (e) {
+      __mixdogMemoryLog(`[pg-adapter] PG reconnect recovery failed for dataDir=${dataDirKey}: ${e?.message || e}\n`)
+      return false
+    }
+  })()
+  _recoverInFlight.set(dataDirKey, p)
+  try {
+    return await p
+  } finally {
+    _recoverInFlight.delete(dataDirKey)
+  }
+}
+
+/**
+ * Run `fn(pool)` against the current pool for (dataDir, schema); on
+ * ECONNREFUSED, recover PG (see _recoverPgConnection) and retry once against
+ * the refreshed pool. Non-ECONNREFUSED errors and cooldown/in-flight misses
+ * propagate the original error unchanged.
+ */
+async function withPgRetry(dataDir, schema, fn) {
+  const key = `${resolve(dataDir)}|${schema}`
+  const pool0 = instances.get(key)?.pool
+  try {
+    return await fn(pool0)
+  } catch (err) {
+    if (err?.code !== 'ECONNREFUSED') throw err
+    const recovered = await _recoverPgConnection(dataDir, schema)
+    if (!recovered) throw err
+    const pool1 = instances.get(key)?.pool
+    if (!pool1) throw err
+    return await fn(pool1)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Instance bootstrap — extensions + schemas (idempotent)
 // ---------------------------------------------------------------------------
@@ -299,7 +423,7 @@ export async function ensurePgInstance(dataDir, opts = {}) {
     await bootstrapInstance(pgPool, resolve(dataDir))
 
     // 5. Build the compat db shim.
-    const db = makeCompatDb(pgPool, schema)
+    const db = makeCompatDb(pgPool, schema, dataDir)
 
     const result = { db, pool: pgPool, host, port, runtimeDir, pgdataDir }
     instances.set(key, result)

package/src/runtime/memory/lib/runtime-fetcher.mjs

@@ -48,6 +48,15 @@ function platformKey() {
   return `${os}-${process.arch}`
 }
 
+function platformKeyCandidates() {
+  const primary = platformKey()
+  const candidates = [primary]
+  if (process.platform === 'win32' && process.arch === 'arm64') {
+    candidates.push('win32-x64')
+  }
+  return candidates
+}
+
 // Fail-closed asset validation. A selected manifest asset is usable only if it
 // is not explicitly marked unsupported AND carries a real downloadable payload:
 // non-empty url, a well-formed 64-hex sha256, and a positive integer size.
@@ -365,25 +374,35 @@ export async function ensureRuntime(dataDir) {
   gcRuntimeDir(runtimeBaseDir, readActiveVersion(runtimeBaseDir))
 
   const manifest = await loadManifest(key)
-  const pkey     = platformKey()
-  const asset    = manifest.assets?.[pkey]
-  if (!asset) {
-    // Platform/arch absent from the manifest entirely (e.g. win32-arm64).
-    // The memory PG runtime cannot start here; fail with a single clear,
-    // actionable message. The memory worker's init().catch reports this as
-    // degraded and the rest of mixdog (agent, tools) keeps working without
-    // memory.
-    const supported = Object.keys(manifest.assets || {})
-      .filter((k) => isUsableAsset(manifest.assets[k]))
-      .join(', ') || '(none)'
-    throw new Error(
-      `[runtime-fetcher] memory runtime not available on ${pkey}: ` +
-      `no runtime asset for this platform/arch in the manifest. ` +
-      `Supported: ${supported}. ` +
-      `Memory is disabled on this platform; the rest of mixdog continues to work.`
-    )
+  const pkey = platformKey()
+  let selectedKey = null
+  let asset = null
+  for (const candidateKey of platformKeyCandidates()) {
+    const candidateAsset = manifest.assets?.[candidateKey]
+    if (isUsableAsset(candidateAsset)) {
+      selectedKey = candidateKey
+      asset = candidateAsset
+      break
+    }
   }
-  if (!isUsableAsset(asset)) {
+  if (!asset) {
+    const primaryAsset = manifest.assets?.[pkey]
+    if (!primaryAsset) {
+      // Platform/arch absent from the manifest entirely (e.g. an exotic arch).
+      // The memory PG runtime cannot start here; fail with a single clear,
+      // actionable message. The memory worker's init().catch reports this as
+      // degraded and the rest of mixdog (agent, tools) keeps working without
+      // memory.
+      const supported = Object.keys(manifest.assets || {})
+        .filter((k) => isUsableAsset(manifest.assets[k]))
+        .join(', ') || '(none)'
+      throw new Error(
+        `[runtime-fetcher] memory runtime not available on ${pkey}: ` +
+        `no runtime asset for this platform/arch in the manifest. ` +
+        `Supported: ${supported}. ` +
+        `Memory is disabled on this platform; the rest of mixdog continues to work.`
+      )
+    }
     // Platform/arch present but explicitly marked unsupported or carrying a
     // placeholder/TBD payload (e.g. linux-arm64). Same graceful-degrade path.
     throw new Error(
@@ -393,6 +412,12 @@ export async function ensureRuntime(dataDir) {
     )
   }
 
+  if (selectedKey !== pkey) {
+    __mixdogMemoryLog(
+      '[runtime-fetcher] win32-arm64 has no native runtime; using win32-x64 under emulation\n'
+    )
+  }
+
   const { url, sha256, size } = asset
   const version = `pg${manifest.pg?.major}.${manifest.pg?.minor}+pgvector-${manifest.pgvector?.version}`
 

package/src/runtime/memory/lib/session-ingest.mjs

@@ -1,21 +1,24 @@
 import crypto from 'node:crypto'
+import { isInternalRuntimeNotificationText } from '../../shared/tool-execution-contract.mjs'
 
 // Side-effect-free helpers for ingest_session (recall fast-track hydration).
 // Extracted from memory/index.mjs so the pure logic (stable identity, sensitive
 // redaction, role/content shaping) can be unit-tested without importing the
 // MCP server entrypoint and its heavy boot-time side effects.
 
-// Roles we persist from an in-memory session transcript. Map provider/runtime
-// role spellings onto the canonical set; unknown roles are dropped.
-const INGEST_SESSION_ROLES = new Set(['user', 'assistant', 'tool', 'system', 'developer'])
+// Roles we persist from an in-memory session transcript (conversation only).
+// Map provider/runtime spellings onto canonical roles; only user/assistant are
+// kept so recall-fasttrack memory does not duplicate protected system prefix.
+const INGEST_SESSION_ROLES = new Set(['user', 'assistant'])
 
 export function normalizeIngestRole(role) {
   const raw = String(role || '').trim().toLowerCase()
   if (!raw) return null
-  if (raw === 'tool_result' || raw === 'function' || raw === 'tool-result') return 'tool'
-  if (raw === 'human') return 'user'
-  if (raw === 'ai' || raw === 'model') return 'assistant'
-  return INGEST_SESSION_ROLES.has(raw) ? raw : null
+  let canonical = raw
+  if (raw === 'tool_result' || raw === 'function' || raw === 'tool-result') canonical = 'tool'
+  else if (raw === 'human') canonical = 'user'
+  else if (raw === 'ai' || raw === 'model') canonical = 'assistant'
+  return INGEST_SESSION_ROLES.has(canonical) ? canonical : null
 }
 
 // Extract the first textual content block from a message content field.
@@ -192,3 +195,109 @@ export function sessionMessageContent(m) {
   }
   return parts.join('\n')
 }
+
+// ── Pure-conversation ingest shaping ──────────────────────────────────────
+//
+// ingest_session persists ONLY real conversation (human prompts + model reply
+// prose). sessionMessageContent (above) is the structured-handoff shaper that
+// inlines tool_call / tool_result traces and is consumed by smoke tests; it is
+// intentionally LEFT UNCHANGED. The functions below are ingest-only and strip
+// everything that is mechanical/synthetic so memory episode rows are pure
+// conversation with zero loss of genuine human/model text.
+
+// Mirror of compact.mjs SUMMARY_PREFIX (the compaction handoff anchor). Copied
+// locally rather than imported because compact.mjs lives under
+// agent/orchestrator/session and pulls in heavy context/offload modules —
+// importing it into the memory layer would create a layering dependency (memory
+// → orchestrator) and risk a boot-time cycle. Keep this string byte-identical
+// to compact.mjs:9; if that anchor changes, update this copy.
+const SUMMARY_PREFIX_INGEST = 'A previous model worked on this task and produced the compacted handoff summary below. Build on the work already done and avoid duplicating it; treat the summary as authoritative context for continuing the task. You also retain the preserved recent turns that follow.'
+
+// Anchored strip of the deterministic user-turn prefix envelopes that
+// manager.mjs prepends to the SINGLE real user message (manager.mjs:3166-3201
+// via prefixUserTurnContent / prefixSessionStartContent / buildSessionStartBlock).
+// Zero-loss design: every rule is anchored to the START of the message and only
+// removes the EXACT shapes manager.mjs produces. A `# Task` / `# Session` etc.
+// appearing mid-message in the human's own text is never touched. When in
+// doubt the rules UNDER-strip (leave content) rather than delete human text.
+function stripUserTurnPrefixEnvelopes(text) {
+  let out = String(text ?? '')
+  // 1) Leading `# Session` block (buildSessionStartBlock: `# Session\nCwd: ...
+  //    \nModel: ...\nWorkflow: ...`, joined by prefixSessionStartContent with a
+  //    trailing `\n\n`). FIELD-ANCHORED: only strip when the line(s) right after
+  //    `# Session\n` are EXACTLY the fixed fields buildSessionStartBlock emits
+  //    (`Cwd: `, `Model: `, `Workflow: `, each on its own line) before the
+  //    blank-line terminator. A human doc that merely STARTS with a `# Session`
+  //    heading followed by free prose (e.g. `프로젝트 회의록입니다`) does NOT match
+  //    — its next line is not a `Cwd:/Model:/Workflow:` field — so it is
+  //    preserved verbatim (zero-loss). Anchored ^.
+  out = out.replace(/^# Session\n(?:(?:Cwd|Model|Workflow): [^\n]*\n)+(?:\n|$)/, '')
+  // 2) Leading `# Additional context\n<body>\n\n` (manager.mjs:3168). Anchored
+  //    to start; body runs up to the next `# ` section boundary or end. The
+  //    `\n\n` separator manager.mjs emits is included.
+  out = out.replace(/^# Additional context\n[\s\S]*?(?=\n# |$)/, '')
+  out = out.replace(/^\n+/, '')
+  // 3) Leading `# Prefetch\n<body>\n\n` (manager.mjs:3171). Same anchoring.
+  out = out.replace(/^# Prefetch\n[\s\S]*?(?=\n# |$)/, '')
+  out = out.replace(/^\n+/, '')
+  // 4) Leading `# Task\n` marker (prefixUserTurnContent: `${contextBlock}# Task\n${content}`).
+  //    Remove ONLY the marker line; everything after it is the human prompt and
+  //    is preserved verbatim. Anchored ^ so a `# Task` in the human's own prose
+  //    (after real text precedes it) is never removed.
+  out = out.replace(/^# Task\n/, '')
+  return out
+}
+
+// Ingest-only message shaper: returns ONLY the human/model prose text, NEVER
+// inlining tool_call / tool_result traces. For user messages, the deterministic
+// manager.mjs prefix envelopes are stripped so only the human's actual prompt
+// remains. The <system-reminder> block is left in place here because
+// cleanMemoryText already removes it downstream (text-utils.cjs:28).
+export function sessionMessageContentForIngest(m) {
+  const base = firstTextContent(m?.content)
+  if (!base) return ''
+  if (normalizeIngestRole(m?.role) === 'user') {
+    return stripUserTurnPrefixEnvelopes(base)
+  }
+  return base
+}
+
+// Row-exclusion predicate for ingest_session. Synthetic / non-conversation
+// rows (reference-files injections, compaction summaries, protected-context
+// `.` acks, internal runtime nudges) are dropped ENTIRELY — they are noise,
+// not conversation. Mirrors the predicates in manager.mjs / compact.mjs but is
+// reimplemented locally to avoid a memory→orchestrator layering dependency.
+export function shouldExcludeIngestMessage(m) {
+  if (!m || typeof m !== 'object') return true
+  const role = normalizeIngestRole(m?.role)
+  const raw = firstTextContent(m?.content)
+  // `Reference files:` synthetic user rows (manager.mjs isReferenceFilesMessage).
+  if (role === 'user' && typeof raw === 'string' && /^Reference files:\s*/i.test(raw.trimStart())) {
+    return true
+  }
+  // Attachment-only placeholder rows (e.g. Discord backend discord.mjs:724
+  // `"(attachment)"` fallback when a message carries no text, only files).
+  // Carries zero retrievable content — excluded so recall isn't polluted
+  // with bare "(attachment)" memory rows.
+  if (role === 'user' && typeof raw === 'string' && raw.trim() === '(attachment)') {
+    return true
+  }
+  // Compaction summary user rows (compact.mjs isSummaryMessage / SUMMARY_PREFIX).
+  if (role === 'user' && typeof raw === 'string' && raw.startsWith(SUMMARY_PREFIX_INGEST)) {
+    return true
+  }
+  // Protected-context `.` ack assistant rows (compact.mjs isProtectedContextAckMessage):
+  // a bare `.` with no tool calls. cleanMemoryText leaves a lone `.` non-empty
+  // (no \p{L}\p{N}), so it would otherwise survive the empty-skip — exclude it.
+  if (role === 'assistant' && typeof raw === 'string' && raw.trim() === '.' && !Array.isArray(m?.toolCalls)) {
+    return true
+  }
+  // Internal runtime nudge `[mixdog-runtime] ...` user rows (loop.mjs:2014-2020)
+  // and other internal runtime notifications (tool-execution-contract).
+  if (role === 'user') {
+    const text = typeof raw === 'string' ? raw : ''
+    if (/^\[mixdog-runtime\]/.test(text.trimStart())) return true
+    if (isInternalRuntimeNotificationText(text)) return true
+  }
+  return false
+}

package/src/runtime/memory/lib/trace-store.mjs

@@ -56,7 +56,7 @@ async function init(client) {
       session_id         TEXT,
       iteration          INTEGER,
       kind               TEXT NOT NULL,
-      role               TEXT,
+      agent              TEXT,
       model              TEXT,
       tool_name          TEXT,
       tool_ms            INTEGER,
@@ -103,12 +103,18 @@ async function init(client) {
     END $$
   `)
 
+  // Drift repair MUST run before index creation: an old cluster whose
+  // trace_events predates the `agent` column would otherwise die right below
+  // at idx_trace_agent_ts (CREATE INDEX references the missing column) before
+  // initAgentTables() ever gets a chance to repair it. Reviewer High fix.
+  await migrateSchemaDrift(client)
+
   // BRIN on ts — ~1000× smaller than btree for append-only timeseries; ideal
   // for time-window range scans where rows arrive in roughly ts order.
   await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_ts_brin      ON trace_events USING BRIN (ts) WITH (pages_per_range = 32)`)
   await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_kind_ts     ON trace_events(kind, ts DESC)`)
   await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_session     ON trace_events(session_id, ts)`)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_role_ts     ON trace_events(role, ts DESC)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_agent_ts    ON trace_events(agent, ts DESC)`)
   await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_model_ts    ON trace_events(model, ts DESC)`)
   await client.query(`CREATE INDEX IF NOT EXISTS idx_trace_tool        ON trace_events(tool_name) WHERE kind = 'tool'`)
   // Span-tree and cross-schema recall↔trace correlation — partial indexes so
@@ -122,13 +128,45 @@ async function init(client) {
   await ensureCurrentAndNextMonthPartitions(client)
 }
 
+// ---------------------------------------------------------------------------
+// Schema-drift repair — ALTER TABLE ... ADD COLUMN IF NOT EXISTS
+// ---------------------------------------------------------------------------
+// Observed failure: pg.log repeatedly logs
+//   column "agent" of relation "trace_events" does not exist
+// and the equivalent for agent_sessions — an older cluster/pgdata created
+// before the `agent` column was added to these two tables, so every INSERT/
+// UPSERT touching it fails forever until manually patched. CREATE TABLE IF
+// NOT EXISTS above is a no-op once the table exists, so it never repairs an
+// already-created table with a stale column set. Run these idempotent
+// ADD COLUMN migrations on every boot (init() and initAgentTables()) so
+// drifted clusters self-heal without a manual ALTER.
+async function migrateSchemaDrift(client) {
+  // Bounded lock wait: nullable ADD COLUMN is metadata-only once the ACCESS
+  // EXCLUSIVE lock is held, but acquiring that lock can queue behind live
+  // readers/writers indefinitely and wedge boot (reviewer Medium). 5s is
+  // generous for a metadata change; on timeout we leave the drift in place
+  // (inserts keep failing as before — no worse) instead of hanging startup.
+  await client.query(`SET LOCAL lock_timeout = '5s'`).catch(() => {})
+  try {
+    await client.query(`ALTER TABLE IF EXISTS trace_events   ADD COLUMN IF NOT EXISTS agent TEXT`)
+    await client.query(`ALTER TABLE IF EXISTS agent_sessions ADD COLUMN IF NOT EXISTS agent TEXT`)
+  } finally {
+    await client.query(`SET LOCAL lock_timeout = DEFAULT`).catch(() => {})
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Agent-specific analytic tables (added post-init via initAgentTables)
 // ---------------------------------------------------------------------------
 
-// Called once per openTraceDatabase boot (after the advisory lock is released).
-// Safe to call concurrently — all DDL is IF NOT EXISTS.
+// Called once per openTraceDatabase boot, inside the BOOTSTRAP advisory-lock
+// scope (see openTraceDatabase) so concurrent first-boot processes don't race
+// this DDL. All statements remain IF NOT EXISTS as a second line of defense.
 export async function initAgentTables(client) {
+  // Repair schema drift on already-created tables before anything else
+  // (trace_events already exists at this point via init(); agent_sessions
+  // is created just below in this same function).
+  await migrateSchemaDrift(client)
   // ── agent_calls: one row per tool invocation ─────────────────────────────
   await client.query(`
     CREATE TABLE IF NOT EXISTS agent_calls (
@@ -175,7 +213,7 @@ export async function initAgentTables(client) {
   await client.query(`
     CREATE TABLE IF NOT EXISTS agent_sessions (
       session_id          TEXT        PRIMARY KEY,
-      role                TEXT,
+      agent               TEXT,
       model               TEXT,
       started_at          TIMESTAMPTZ,
       last_seen_at        TIMESTAMPTZ,
@@ -186,6 +224,10 @@ export async function initAgentTables(client) {
       total_output_tokens BIGINT      NOT NULL DEFAULT 0
     )
   `)
+
+  // Repair drift again post-creation for agent_sessions (belt-and-suspenders;
+  // no-op when the table was freshly created above with the column present).
+  await migrateSchemaDrift(client)
 }
 
 // ---------------------------------------------------------------------------
@@ -289,14 +331,14 @@ export async function insertAgentCalls(db, events) {
   // Upsert session summaries — accumulate from tool+llm rows in this batch
   const sessionMap = new Map()
   for (const r of toolRows) {
-    const s = sessionMap.get(r.session_id) ?? { tool_calls: 0, llm_calls: 0, max_iteration: 0, total_input: 0n, total_output: 0n, ts0: r.ts, ts1: r.ts, role: null, model: null }
+    const s = sessionMap.get(r.session_id) ?? { tool_calls: 0, llm_calls: 0, max_iteration: 0, total_input: 0n, total_output: 0n, ts0: r.ts, ts1: r.ts, agent: null, model: null }
     s.tool_calls += 1
     if (r.iteration != null && r.iteration > s.max_iteration) s.max_iteration = r.iteration
     if (r.ts < s.ts0) s.ts0 = r.ts; if (r.ts > s.ts1) s.ts1 = r.ts
     sessionMap.set(r.session_id, s)
   }
   for (const r of llmRows) {
-    const s = sessionMap.get(r.session_id) ?? { tool_calls: 0, llm_calls: 0, max_iteration: 0, total_input: 0n, total_output: 0n, ts0: r.ts, ts1: r.ts, role: null, model: null }
+    const s = sessionMap.get(r.session_id) ?? { tool_calls: 0, llm_calls: 0, max_iteration: 0, total_input: 0n, total_output: 0n, ts0: r.ts, ts1: r.ts, agent: null, model: null }
     s.llm_calls += 1
     s.total_input  += BigInt(r.input_tokens ?? 0)
     s.total_output += BigInt(r.output_tokens ?? 0)
@@ -305,13 +347,13 @@ export async function insertAgentCalls(db, events) {
     if (r.ts < s.ts0) s.ts0 = r.ts; if (r.ts > s.ts1) s.ts1 = r.ts
     sessionMap.set(r.session_id, s)
   }
-  // Also pick up role from preset_assign events in the same batch
+  // Also pick up agent from preset_assign events in the same batch
   for (const ev of events) {
-    if (ev.kind === 'preset_assign' && ev.role) {
+    if (ev.kind === 'preset_assign' && ev.agent) {
       const sid = ev.session_id ?? ev.sessionId ?? null
       if (!sid) continue
       const s = sessionMap.get(sid)
-      if (s) s.role = ev.role
+      if (s) s.agent = ev.agent
     }
   }
   // Fix 5 — upsert sessions for preset_assign-only batches (no tool/llm rows yet)
@@ -326,32 +368,32 @@ export async function insertAgentCalls(db, events) {
       tool_calls: 0, llm_calls: 0, max_iteration: 0,
       total_input: 0n, total_output: 0n,
       ts0: tsIso, ts1: tsIso,
-      role: ev.role ?? null, model: ev.model ?? null,
+      agent: ev.agent ?? null, model: ev.model ?? null,
     })
   }
 
   // Coalesce agent_sessions upserts: batch all sessions in one unnest INSERT.
   // Also within the same transaction.
   if (sessionMap.size > 0) {
-    const sids = [], roles = [], models = [], ts0s = [], ts1s = [],
+    const sids = [], agents = [], models = [], ts0s = [], ts1s = [],
           tcalls = [], lcalls = [], maxiters = [], tinputs = [], toutputs = []
     for (const [sid, s] of sessionMap) {
-      sids.push(sid); roles.push(s.role); models.push(s.model)
+      sids.push(sid); agents.push(s.agent); models.push(s.model)
       ts0s.push(s.ts0); ts1s.push(s.ts1)
       tcalls.push(s.tool_calls); lcalls.push(s.llm_calls)
       maxiters.push(s.max_iteration)
       tinputs.push(String(s.total_input)); toutputs.push(String(s.total_output))
     }
     await client.query(`
-      INSERT INTO agent_sessions (session_id, role, model, started_at, last_seen_at, tool_calls, llm_calls, max_iteration, total_input_tokens, total_output_tokens)
-      SELECT u.session_id, u.role, u.model,
+      INSERT INTO agent_sessions (session_id, agent, model, started_at, last_seen_at, tool_calls, llm_calls, max_iteration, total_input_tokens, total_output_tokens)
+      SELECT u.session_id, u.agent, u.model,
              u.started_at::timestamptz, u.last_seen_at::timestamptz,
              u.tool_calls::int, u.llm_calls::int, u.max_iteration::int,
              u.total_input_tokens::bigint, u.total_output_tokens::bigint
       FROM unnest($1::text[],$2::text[],$3::text[],$4::text[],$5::text[],$6::int[],$7::int[],$8::int[],$9::text[],$10::text[])
-           AS u(session_id,role,model,started_at,last_seen_at,tool_calls,llm_calls,max_iteration,total_input_tokens,total_output_tokens)
+           AS u(session_id,agent,model,started_at,last_seen_at,tool_calls,llm_calls,max_iteration,total_input_tokens,total_output_tokens)
       ON CONFLICT (session_id) DO UPDATE SET
-        role                = COALESCE(EXCLUDED.role, agent_sessions.role),
+        agent               = COALESCE(EXCLUDED.agent, agent_sessions.agent),
         model               = COALESCE(EXCLUDED.model, agent_sessions.model),
         started_at          = LEAST(agent_sessions.started_at, EXCLUDED.started_at),
         last_seen_at        = GREATEST(agent_sessions.last_seen_at, EXCLUDED.last_seen_at),
@@ -360,7 +402,7 @@ export async function insertAgentCalls(db, events) {
         max_iteration       = GREATEST(agent_sessions.max_iteration, EXCLUDED.max_iteration),
         total_input_tokens  = agent_sessions.total_input_tokens  + EXCLUDED.total_input_tokens,
         total_output_tokens = agent_sessions.total_output_tokens + EXCLUDED.total_output_tokens
-    `, [sids, roles, models, ts0s, ts1s, tcalls, lcalls, maxiters, tinputs, toutputs])
+    `, [sids, agents, models, ts0s, ts1s, tcalls, lcalls, maxiters, tinputs, toutputs])
   }
 
     await client.query('COMMIT')
@@ -513,14 +555,19 @@ export async function openTraceDatabase(dataDir) {
           // are pre-created for this boot.
           await ensureCurrentAndNextMonthPartitions(client)
         }
+        // Agent-specific analytic tables — moved inside the advisory-lock
+        // scope (was previously run after client.release() with no lock,
+        // letting concurrent first-boot processes race the agent_calls/
+        // agent_llm/agent_sessions CREATE TABLE + migrateSchemaDrift DDL).
+        // Reuses the same lock-holding client/session; still idempotent
+        // (IF NOT EXISTS everywhere) but no longer racy across processes.
+        await initAgentTables(client)
       } finally {
         await client.query(`SELECT pg_advisory_unlock(${BOOTSTRAP_LOCK_KEY})`)
       }
     } finally {
       client.release()
     }
-    // Agent-specific analytic tables — idempotent, no advisory lock needed.
-    await initAgentTables(db)
 
     dbs.set(key, db)
 
@@ -557,7 +604,7 @@ export async function openTraceDatabase(dataDir) {
 // ---------------------------------------------------------------------------
 
 const TRACE_COLS = [
-  'ts', 'session_id', 'iteration', 'kind', 'role', 'model',
+  'ts', 'session_id', 'iteration', 'kind', 'agent', 'model',
   'tool_name', 'tool_ms', 'input_tokens', 'output_tokens',
   'cached_tokens', 'cache_write_tokens', 'duration_ms',
   'error_message', 'payload', 'parent_span_id', 'entry_id',
@@ -755,7 +802,7 @@ export async function insertTraceEvents(db, events) {
       ev.session_id ?? null,
       ev.iteration != null ? Number(ev.iteration) : null,
       String(ev.kind ?? 'unknown'),
-      ev.role ?? null,
+      ev.agent ?? null,
       ev.model ?? null,
       ev.tool_name ?? null,
       ev.tool_ms != null ? Number(ev.tool_ms) : null,