// ============================================================================
// internal-backfill-worker.ts — daemon-owned Email Backfill Pipeline
//
// Default window: 90 days (configurable via --since flag or Elyntic Desktop UI)
// Users can adjust the window from the Elyntic Desktop sync settings panel.
//
// Phase 1: Fetch Gmail messages since --since â†’ gmail-index-30d.json
//   â€¢ If Gmail token is fresh: calls GmailProvider.fetchAllInbox()
//   â€¢ If token expired or --offline: filters existing gmail-index.json by date
// Phase 2: ingestEmailIndex() â†’ Graph graph population
//   â€¢ Writes Email nodes, Person nodes, SENT_FROM/SENT_TO/KNOWS/HAS_IDENTITY edges
// Phase 2.5: Full enrichment pipeline (all 34 signal dependencies)
//   â€¢ T0-PRE: self-ID unification â”‚ T0: Emailâ†’Episode, KNOWS anchoring, person stats
//   â€¢ T1: MAGE centrality â”‚ T1.5: temporal features â”‚ T1.6: veto fields
//   â€¢ T2: metadata signals â”‚ T3: enrichAll (FAVEE/Dunbar/quality/trajectories)
//   â€¢ T4: snapshots, trajectory velocity, resilience, orphan cleanup
// Phase 3: TriageOrchestrator.run() with static adapter â†’ briefing + AI drafts
// Phase 4: generateDashboard() â†’ dashboard.html
//
// PRIVATE WORKER — launched only by daemon/lib/backfill-coordinator.js.
// Resumable via checkpoint in $ELYNTIC_ROOT/data/ (or OS-appropriate fallback)
// ============================================================================

// Establish backfill-only broker and timeout settings before ESM evaluates dependencies.
import './lib/backfill-preload.ts';
// ONE SQLite library in this process before any store opens (lib/sqlite-single-binding.js):
// this worker inherits the Desktop ABI preload's library and also opens stores through the
// published BETTER_SQLITE3_BINDING; two libraries drop each other's POSIX locks.
import './lib/sqlite-single-binding-preload.cjs';
import { writeFileSync, appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
import { iterateJsonArrayFile, readEmailIndexFile, readEmailCheckpointFile, writeJsonArrayFile } from './lib/email/json-array-file.ts';
import { join, resolve } from 'node:path';
import { homedir } from 'node:os';
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';

// â”€â”€ Backfill forensic logger â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
// Writes one JSONL line per phase step: id, label, status, durationMs, error.
// File: helios-agent-main/logs/backfill-forensic.jsonl
// Append-only, UTF-8, non-blocking (sync write is fine â€” one line per step, not per query).
// Referenced in LOGS.md under "Backfill forensic log".
const _FORENSIC_LOG_DIR  = process.env.ELYNTIC_BACKFILL_ACCOUNT_DATA_DIR
  ? join(process.env.ELYNTIC_BACKFILL_ACCOUNT_DATA_DIR, 'logs')
  : join(__dirname, 'logs');
const _FORENSIC_LOG_FILE = join(_FORENSIC_LOG_DIR, 'backfill-forensic.jsonl');
function _forensicWrite(entry: Record<string, unknown>): void {
  try {
    if (!existsSync(_FORENSIC_LOG_DIR)) mkdirSync(_FORENSIC_LOG_DIR, { recursive: true });
    appendFileSync(_FORENSIC_LOG_FILE, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n', 'utf8');
  } catch { /* non-fatal â€” never block the pipeline on log writes */ }
}
// Write run-start entry so log is always anchored even if phases fail
_forensicWrite({ event: 'run_start', args: process.argv.slice(2) });

import { GmailProvider } from './extensions/email/providers/gmail.ts';
import { refreshAccessToken, resolveTokenPath } from './extensions/email/auth/inbox-dog.ts';
import { ingestEmailIndex, EMAIL_BACKFILL_CHECKPOINT_PATH } from './extensions/email/backfill.ts';
import {
  assertCanonicalGraphProjectionReady,
  TriageOrchestrator,
  TRIAGE_BACKFILL_PRESET,
} from './lib/triage-core/orchestrator.ts';
import { parseDuration as parseSince } from './lib/time-utils.ts';
import { parseEmailAddress, splitAddressList } from './lib/email-utils.ts';
import type { TriageItem } from './lib/triage-core/types.ts';

import { generateDashboard } from './lib/triage-core/dashboard-generator.ts';
import { loadCheckpoint, saveCheckpoint, clearCheckpoint } from './lib/backfill-utils.ts';
import { getAccount, getEnabledAccounts, getDefaultAccount, resolveSelfEmailDomains } from './extensions/email/auth/accounts.ts';
import type { ChannelAdapter, RawMessage } from './lib/triage-core/orchestrator.ts';
import { LiveGmailAdapter, StaticGmailAdapter } from './lib/adapters/gmail-adapters.ts';
import { isLenderOrLegalEmail, buildAttorneyForwardDraft } from './lib/triage-core/legal-routing.ts';
import { fetchLegalEnrichment } from './lib/triage-core/legal-enrichment.ts';
import { ensureSelfPerson } from './lib/triage-core/mental-model/ensure-self-person.ts';
import { upsertEmailCacheBatch, loadEmailCache, loadEmailCacheMessageIds, countEmailCache, clearEmailCache } from './lib/triage-core/triage-sql-store.ts';
import { estimateBackfillCost, providerTypeForEstimator } from './lib/triage-core/backfill-cost-estimator.ts';
import {
  assertBackfillGraphPolicy,
  assertCoordinatedEnrichmentOnly,
  backfillWorkerDiagnosticCode,
} from './lib/backfill-graph-policy.ts';
import { legacyGraphEnabled, renderGraphDegradationReport } from './lib/backfill-graph-mode.ts';
import { canonicalBatchRecordsToRawMessages } from './lib/triage-core/canonical-projection-enrichment.ts';
import { exitCoordinatedWorkerAfterFlush } from './lib/coordinated-worker-exit.ts';
import { STATUS, assessPhasePersistence, persistenceFields, readCanonicalPersonCount } from './lib/backfill-accounting.js';

const _COORDINATOR_PHASE_INDEX = process.argv.indexOf('--coordinator-phase');
const COORDINATOR_PHASE = _COORDINATOR_PHASE_INDEX >= 0
  ? process.argv[_COORDINATOR_PHASE_INDEX + 1]
  : null;
const COORDINATED = process.env.ELYNTIC_BACKFILL_COORDINATED === '1';
const COORDINATED_FETCH = COORDINATED && COORDINATOR_PHASE === 'fetch';
const COORDINATED_ENRICH = COORDINATED && COORDINATOR_PHASE === 'enrich';

if (COORDINATED) {
  const parentPid = Number(process.env.ELYNTIC_BACKFILL_PARENT_PID || 0);
  if (!Number.isInteger(parentPid) || parentPid <= 0) {
    throw new Error('coordinated worker requires ELYNTIC_BACKFILL_PARENT_PID');
  }
  const parentWatch = setInterval(() => {
    try { process.kill(parentPid, 0); }
    catch { process.exit(75); }
  }, 1000);
  parentWatch.unref();
}

// â”€â”€ Backfill resource tuning â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
// These values are calibrated from run bf5 crash analysis (2026-06-30):
//
// GRAPH_QUERY_SEMAPHORE_SIZE=30
//   Default semaphore is 20. classifyConcurrency=2 Ã— 14 queries = 28 max concurrent.
//   28 > 20 caused semaphore exhaustion (Active:20/20, Queue:27) â†’ query drops â†’ crash.
//   30 gives 2 slots of headroom above the worst-case load.
//   Source: lib/query-semaphore.js QuerySemaphore.maxSlots
//
// TOURNAMENT_WORKERS=2
//   Default is 3 pool slots Ã— ~200MB each = 600MB for elyntic-rpc.
//   Qwen3 (~862MB) + Bolt Java (~512MB) + backfill (~200MB) = ~1.6GB base.
//   Adding 600MB totals ~2.2GB â€” Windows pressure-kills elyntic-rpc (SIGTERM â†’ code=null).
//   2 slots = 400MB extra â†’ ~2.0GB total â€” manageable on 4GB+ machines.
//   Source: daemon/lib/tournament-node-runner.js MAX_WORKERS
//
// QWEN3_MAX_THREADS=4
//   Default 16 threads holds all CPU cores, starving elyntic-rpc of scheduling.
//   4 threads frees 12 cores. Diminishing returns above 4 for 0.6B model anyway.
//   Source: node-llama-cpp LlamaOptions.maxThreads, LlamaContextOptions.threads
//
// QWEN3_CONTEXT_SIZE=2048
//   Default 4096 uses ~80MB KV-cache. 2048 uses ~40MB. Emails are short (< 2048 tokens).
//   Saves ~40MB native RAM for pool slots and Bolt.
//   Source: node-llama-cpp LlamaContextOptions.contextSize
process.env.GRAPH_QUERY_SEMAPHORE_SIZE    = process.env.GRAPH_QUERY_SEMAPHORE_SIZE    ?? '30';
// Qwen3-0.6B cannot produce the complex JSON the extractors need (key-facts,
// open_questions, roles all returned zero signal). Pin the 8B model; qwen-llm.ts
// honors OLLAMA_CHAT_MODEL before auto-discovering from /api/tags.
process.env.OLLAMA_CHAT_MODEL = process.env.OLLAMA_CHAT_MODEL ?? 'qwen3:8b';
// Self-identity domains: without these, outbound mail from own domains is
// misclassified as inbound (2026-07-06 incident). They are NOT defaulted here: this
// line used to default them to one person's domains, which shipped that person's
// identity to every install and was silently wrong on all of them. Phase 5 derives
// them at run time (resolveSelfEmailDomains: SELF_EMAIL_DOMAINS override, owner
// mailbox, enabled accounts) and refuses by SELF_EMAIL_DOMAINS_UNRESOLVED.
// Signal to unified-graph.ts that we are in backfill mode â€” suppress background DDL
// (CREATE INDEX for SessionOutcome, CortexDecisionLog) that fires on module load and
// times out against a loaded Graph instance, consuming semaphore slots during Phase 1.
process.env.ELYNTIC_BACKFILL_MODE = '1';
// Raise query semaphore execution ceiling from 35s to 120s.
// Background DDL (CREATE INDEX FOR SessionOutcome, CortexDecisionLog) from brain/cortex
// startup fires during Phase 1 and takes >35s on a loaded Graph instance.
// GRAPH_QUERY_EXECUTION_TIMEOUT_MS is read by query-semaphore.js at singleton creation.
// Setting it here (before any import) ensures the semaphore is created with 120s ceiling
// even if jiti eagerly loads query-semaphore.js before env-preload.ts runs.
// Source: lib/query-semaphore.js line 36-39 â€” reads env var at singleton construction time.
process.env.GRAPH_QUERY_EXECUTION_TIMEOUT_MS = process.env.GRAPH_QUERY_EXECUTION_TIMEOUT_MS ?? '120000';
// TOURNAMENT_WORKERS: cap at 2 on Windows to avoid working-set pressure.
// Qwen3 (~862MB) + Bolt Java (~512MB) + backfill (~200MB) = ~1.6GB base on Windows.
// 2 extra pool slots Ã— ~200MB = ~2.0GB â€” approaches 4GB machine limits.
// On macOS/Linux virtual memory management handles this gracefully; use 3 (default).
process.env.TOURNAMENT_WORKERS = process.env.TOURNAMENT_WORKERS ?? (process.platform === 'win32' ? '2' : '3');
process.env.QWEN3_MAX_THREADS             = process.env.QWEN3_MAX_THREADS             ?? '4';
process.env.QWEN3_CONTEXT_SIZE            = process.env.QWEN3_CONTEXT_SIZE            ?? '2048';

// â”€â”€ Pre-warm graph-transport broker before Phase 1 â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
// The broker auto-starts on first require('./lib/graph/graph-transport.js') which normally
// fires mid-Phase-1 when unified-graph.js is loaded. This causes the warm gate to
// open after the 8s fail-open timer (not via IPC signal) because the broker hasn't
// had time to start. Requiring it here gives the broker the full Phase 1 duration
// (30-60s of Gmail fetch) to start and send its IPC ready signal before any graph
// queries are issued.
// Source: lib/graph/graph-transport.js lines 117-118 â€” failOpenMs 8s (not managed) vs 30s (managed)
//
// BACKFILL-GRAPH-SWEEP-1: gated behind the legacy opt-in. This require IS a
// bolt connection attempt — the broker auto-starts on first require, by design,
// which is the whole point of the pre-warm. Unconditionally, it meant every
// backfill process opened a graph connection during module load, before a
// single phase ran and regardless of whether any phase would use it. No amount
// of removing Cypher downstream could produce a zero-bolt run while it stood.
if (!COORDINATED_FETCH && legacyGraphEnabled()) {
  try { require('./lib/graph/graph-transport.js'); } catch { /* non-fatal — broker will start lazily */ }
}

// ── Propagate the graph veto to every CHILD process ──────────────────────────
// BACKFILL-GRAPH-SWEEP-1, found by the live warm run (a --dry-run could
// never have found it: dry-run skips Phase 3, so the child processes are never
// spawned).
//
// Phase 3 pre-warms a tournament pool, and daemon/lib/tournament-node-runner.js
// spawns those slots with `env: { ...process.env, ... }`. The slots are separate
// Node processes that load the full graph stack themselves, so every gate added
// in THIS file was invisible to them: 21+ bolt connections appeared the instant
// the pool spawned, on a run whose parent had opened exactly zero.
//
// Setting the veto here rather than editing the runner is deliberate. It is one
// line at the process boundary instead of N edits across shared infrastructure
// that other features also spawn through, it rides the `...process.env` spread
// that every child spawner already uses, and ELYNTIC_SKIP_GRAPH=1 is the
// repo's pre-existing hard veto which graph-transport and the rest of the stack
// already honour. It is an information-flow fix, not a per-call-site patch.
//
// Guarded so an explicit legacy opt-in is never overridden.
if (!legacyGraphEnabled()) {
  process.env.ELYNTIC_SKIP_GRAPH = '1';
}

// â”€â”€ E1+E7 (resolved): entity-extractor and summary-generator now default to
// Qwen3 directly â€” no injection needed. setExtractionLLM/setSummaryLLM are
// retained as test seams only.
// QWEN3_BATCH_SIZE=256 â€” reduced from default 512.
// Source 7 (LlamaContextOptions): "For CPU with limited RAM, lowering batchSize reduces
//   peak memory at cost of prompt processing speed."
// Source 21 (OpenMP benchmark): Prompt processing scales with thread count; batchSize
//   affects peak per-batch memory, not per-token generation memory.
// 256 = 2 batches of 256 for a ~500-token prompt. Saves ~25MB peak vs batchSize=512.
process.env.QWEN3_BATCH_SIZE              = process.env.QWEN3_BATCH_SIZE              ?? '256';
// TOURNAMENT_GLOBAL_TIMEOUT_MS=120000 (2 min) for backfill â€” reduced from 300s default.
// Rationale: with classifyConcurrency=2 and pool=2 warm slots, worst case per tournament:
//   Round 1: 9 matches (3 criteria Ã— C(3,2) pairs), pool=2 â†’ 5 batches Ã— ~10s LLM = ~50s.
//   Thompson Sampling rounds (max 6): 6 Ã— 2 matches Ã— 10s = ~120s total.
// 120s gives 0s headroom for TS rounds + 50s for Round 1 = worst case exactly 120s.
// If slots SIGTERM (memory pressure), 120s fails fast â€” reduces wasted wall-clock from 5min to 2min.
// Source: tournament-node-runner.js TOURNAMENT_GLOBAL_TIMEOUT_MS + MAX_TS_ROUNDS constants.
process.env.TOURNAMENT_GLOBAL_TIMEOUT_MS  = process.env.TOURNAMENT_GLOBAL_TIMEOUT_MS  ?? '180000';
// Key-facts extraction is now flushed synchronously by the orchestrator before
// assembleMentalModel() in backfill mode (flushFactExtractionQueue). The DISABLE
// env vars have been removed so first-time contacts get key facts extracted.
// See: lib/triage-core/orchestrator.ts â€” "Flush key-facts queue in backfill mode"

// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------
// ELYNTIC_DATA: directory where gmail index and data files are stored.
// Resolution order (matches accounts.ts convention):
//   1. ELYNTIC_DATA env var (explicit override)
//   2. ~/.elyntic/outreach (new preferred location)
//   3. ~/.pi/outreach (legacy â€” warn and continue)
const _elynticNewPath = join(homedir(), '.elyntic', 'outreach');
const _coordinatedAccountData = process.env.ELYNTIC_BACKFILL_ACCOUNT_DATA_DIR || null;
const _OUTREACH_BASE = _coordinatedAccountData
  ? join(_coordinatedAccountData, 'outreach')
  : process.env.ELYNTIC_DATA
    ?? (existsSync(_elynticNewPath) ? _elynticNewPath : null)
    ?? join(homedir(), '.pi', 'outreach');
if (!process.env.ELYNTIC_DATA && !_coordinatedAccountData) {
  const isLegacy = _OUTREACH_BASE.includes('.pi');
  process.stderr.write(
    `[internal-backfill-worker] ELYNTIC_DATA env var not set — using ${isLegacy ? 'legacy' : 'default'}: ${_OUTREACH_BASE}\n` +
    (isLegacy ? `  To silence: set ELYNTIC_DATA=${_OUTREACH_BASE} or migrate to ~/.elyntic/outreach\n` : '')
  );
}
const DATA_DIR = join(_OUTREACH_BASE, 'data');

// ELYNTIC_ROOT: repo root. Used for checkpoint files that live alongside the agent.
// On all platforms, resolve from env var first, then from __dirname-equivalent, then ~/.elyntic.
// This avoids hardcoding 'helios-agent' as a directory name.
const _require = createRequire(import.meta.url);
// Force-update the query-semaphore singleton execution timeout immediately.
// jiti eagerly evaluates all modules it imports, creating the singleton BEFORE
// our process.env.GRAPH_QUERY_EXECUTION_TIMEOUT_MS assignment at line 100 runs.
// Result: singleton is created with default 35s, not our 120s. This call patches it.
// Source: lib/query-semaphore.js updateExecutionTimeout() â€” added for this exact case.
try {
  const { setExecutionTimeout: _setExecTimeout } = _require('./lib/query-semaphore.js') as any;
  _setExecTimeout?.(120000);
} catch { /* non-fatal â€” semaphore may not be loaded yet */ }
const { ELYNTIC_ROOT: _ELYNTIC_ROOT } = _require('./lib/elyntic-root.js') as { ELYNTIC_ROOT: string };
const ELYNTIC_DATA_DIR = _coordinatedAccountData
  ? join(_coordinatedAccountData, 'runtime')
  : process.env.ELYNTIC_ROOT
    ? join(process.env.ELYNTIC_ROOT, 'data')
    : join(_ELYNTIC_ROOT, 'data');

const {
  assertBatchForRun,
  isBatchAcknowledged,
  readGraphProjectionRunManifest,
  readCommittedCursor,
  stageEmailIngestBatches,
} = _require('./daemon/lib/email-ingest-spool.js') as any;
const { isStoredAttachment, materializeAvailableInboundAttachments } = _require(
  './daemon/lib/email-attachment-store.js',
) as any;
const {
  admittedBackfillMessages: admitPinnedBackfillMessages,
  coordinatedWindow,
} = _require('./lib/backfill-window.js') as any;

const CHECKPOINT_PATH = join(ELYNTIC_DATA_DIR, 'email-backfill-30d-checkpoint.json');

// ── WS3 Preflight — fail loudly on misconfiguration ─────────────────────────
// A wrong self-ID silently zeroes the whole enrichment pipeline (79 modules
// fall back to a hardcoded ID with no KNOWS edges); a missing Ollama model
// turns every LLM step into timeout loops. Validate everything that can
// silently no-op BEFORE any phase runs. --force downgrades failures to warnings.
async function runPreflight(opts: { force: boolean; selfEmail?: string }): Promise<void> {
  const rows: Array<[string, string, string]> = [];
  let hardFail = false;

  // 1. Canonical SQL reachable + writable.
  //
  // BACKFILL-GRAPH-SWEEP-1: this check used to be a Graph write probe
  // whose failure set hardFail and aborted the entire run. That made the graph
  // — an optional, disposable projection under DATA-MODEL-AUTHORITY Authority 3
  // — a hard precondition for ingesting mail into the canonical store, which is
  // exactly backwards. The store that MUST be writable is the canonical one.
  try {
    const { _getDb } = _require('./lib/triage-core/triage-sql-store.ts') as any;
    const db = _getDb();
    db.prepare('SELECT 1').get();
    rows.push(['canonical-sql', 'OK', 'read probe succeeded']);
  } catch (e: any) {
    hardFail = true;
    rows.push(['canonical-sql', 'FAIL', String(e?.message || '').slice(0, 80)]);
  }

  // 1b. Legacy graph engine — probed ONLY when explicitly opted in, and never a
  // hard fail. A graph-free run is supported and degraded, not refused.
  let mgOk = false;
  if (legacyGraphEnabled()) {
    try {
      const { rawWrite } = _require('./lib/graph/graph-transport.js') as any;
      await rawWrite('CREATE (n:PreflightProbe {ts: timestamp()}) WITH n DETACH DELETE n', {});
      mgOk = true;
      rows.push(['graph(legacy)', 'OK', 'write probe succeeded']);
    } catch (e: any) {
      rows.push(['graph(legacy)', 'WARN', `opted in but unreachable — enrichment will degrade: ${String(e?.message || '').slice(0, 60)}`]);
    }
  } else {
    rows.push(['graph(legacy)', 'OFF', 'not opted in (ELYNTIC_BACKFILL_LEGACY_GRAPH=1 to enable)']);
  }

  // 2. Self-ID: env var must be set AND match a Person node in the graph.
  try {
    const { resolveSelfId } = await import('./lib/triage-core/self-identity.ts');
    const selfId = await resolveSelfId(opts.selfEmail);
    if (mgOk) {
      const { rawRead } = _require('./lib/graph/graph-transport.js') as any;
      const rs = await rawRead('MATCH (p:Person {id: $id}) RETURN p.isSelf AS isSelf LIMIT 1', { id: selfId });
      if (rs.length === 0) {
        const actual = await rawRead('MATCH (p:Person) WHERE p.isSelf = true RETURN p.id AS id LIMIT 1', {});
        if (actual[0]?.id) {
          // env points at a node that does not exist while the graph HAS a
          // self node — the exact silent-zero machine from the 07-08 forensics.
          hardFail = true;
          rows.push(['self-id', 'FAIL', `ELYNTIC_SELF_ID=${selfId} not in graph; graph self node is ${actual[0].id}`]);
        } else {
          rows.push(['self-id', 'WARN', `${selfId} not in graph yet (fresh graph — ensureSelfPerson will create it)`]);
        }
      } else {
        process.env.ELYNTIC_SELF_ID = selfId;
        rows.push(['self-id', 'OK', selfId]);
      }
    } else {
      rows.push(['self-id', 'WARN', `${selfId} (graph unreachable — not verified)`]);
    }
  } catch (e: any) {
    hardFail = true;
    rows.push(['self-id', 'FAIL', String(e?.message || '').slice(0, 110)]);
  }

  // 3. Ollama chat + embed models present
  try {
    const resp = await fetch(`${process.env.OLLAMA_URL || 'http://localhost:11434'}/api/tags`, { signal: AbortSignal.timeout(5000) });
    const tags = await resp.json() as { models?: Array<{ name: string }> };
    const names = (tags.models ?? []).map(m => m.name);
    const chat = process.env.OLLAMA_CHAT_MODEL || 'qwen3:8b';
    const embed = process.env.OLLAMA_EMBED_MODEL || 'nomic-embed-text';
    const has = (want: string) => names.some(n => n === want || n.split(':')[0] === want.split(':')[0] && want.indexOf(':') === -1);
    const missing = [chat, embed].filter(m => !has(m));
    if (missing.length) {
      hardFail = true;
      rows.push(['ollama', 'FAIL', `missing model(s): ${missing.join(', ')} — ollama pull <model>`]);
    } else {
      rows.push(['ollama', 'OK', `${chat} + ${embed}`]);
    }
  } catch (e: any) {
    hardFail = true;
    rows.push(['ollama', 'FAIL', `unreachable: ${String(e?.message || '').slice(0, 60)}`]);
  }

  // 4. Checkpoint dir writable
  try {
    mkdirSync(ELYNTIC_DATA_DIR, { recursive: true });
    const probe = join(ELYNTIC_DATA_DIR, '.preflight-probe');
    writeFileSync(probe, 'ok');
    _require('node:fs').rmSync(probe);
    rows.push(['checkpoint-dir', 'OK', ELYNTIC_DATA_DIR]);
  } catch (e: any) {
    hardFail = true;
    rows.push(['checkpoint-dir', 'FAIL', String(e?.message || '').slice(0, 80)]);
  }

  // 5. Channel gates — skipped channels must be visible, not console.log noise
  if (process.platform !== 'darwin' && !process.env.IMESSAGE_DB_PATH) {
    rows.push(['imessage', 'SKIP', 'non-darwin and IMESSAGE_DB_PATH unset']);
    _forensicWrite({ event: 'step_skip', id: 'phase1b-imessage', reason: 'non-darwin, IMESSAGE_DB_PATH unset' });
  }

  console.log('\nPREFLIGHT');
  for (const [check, status, detail] of rows) {
    console.log(`  ${status.padEnd(5)} ${check.padEnd(15)} ${detail}`);
  }
  _forensicWrite({ event: hardFail ? 'preflight_fail' : 'preflight_ok', rows });

  if (hardFail && !opts.force) {
    console.error('\nPreflight failed — refusing to start (use --force to override).');
    process.exit(2);
  }
  if (hardFail) console.warn('\nPreflight failures overridden by --force.');
}

// ── WS1 Run verdict — the completion banner can lie; the graph doesn't ──────
// One reviewed constant (Goodhart guard: loosening a threshold is a visible diff).
// VERDICT_MIN_SCALE scales minimums for canary/sample runs (WS6).
const VERDICT_CHECKS: Array<{ id: string; cypher: string; min: number }> = [
  { id: 'person_embeddings', cypher: 'MATCH (p:Person) WHERE p.embedding IS NOT NULL RETURN count(p) AS n', min: 100 },
  { id: 'key_facts',         cypher: 'MATCH (kf:KeyFact) RETURN count(kf) AS n', min: 50 },
  { id: 'favee_edges',       cypher: 'MATCH ()-[k:KNOWS]->() WHERE k.favee IS NOT NULL RETURN count(k) AS n', min: 50 },
  { id: 'temporal_features', cypher: 'MATCH ()-[k:KNOWS]->() WHERE k.temporalUpdatedAt IS NOT NULL RETURN count(k) AS n', min: 50 },
  { id: 'strength',          cypher: 'MATCH (p:Person) WHERE p.relationshipStrength IS NOT NULL RETURN count(p) AS n', min: 100 },
  { id: 'snapshots',         cypher: 'MATCH (s:StrengthSnapshot) RETURN count(s) AS n', min: 100 },
  { id: 'summaries',         cypher: 'MATCH (p:Person) WHERE p.summary IS NOT NULL RETURN count(p) AS n', min: 50 },
];

async function runVerdict(): Promise<void> {
  // BACKFILL-GRAPH-SWEEP-1: every VERDICT_CHECK is Cypher over enrichment
  // output that only Phase 2.5 produces. With no graph engine they all read 0,
  // score as FAIL, and exit 3 - reporting a FAILED RUN for a backfill whose
  // canonical ingest completed perfectly. That is a false negative, and it is
  // as dishonest as the false positive this verdict was built to catch.
  //
  // So the graph checks are reported UNAVAILABLE rather than 0, and they do not
  // set a failing exit code. What IS asserted is the canonical outcome: person
  // and email rows actually present in SQL. A run that ingested nothing still
  // fails here.
  if (!legacyGraphEnabled()) {
    let persons = -1;
    let emails = -1;
    try {
      const { _getDb } = _require('./lib/triage-core/triage-sql-store.ts') as any;
      const db = _getDb();
      persons = Number((db.prepare('SELECT COUNT(*) AS n FROM triage_persons').get() as any)?.n ?? -1);
      try {
        emails = Number((db.prepare('SELECT COUNT(*) AS n FROM triage_email_cache').get() as any)?.n ?? -1);
      } catch { emails = -1; }
    } catch { /* leave -1 */ }

    const canonicalOk = persons > 0 || emails > 0;
    console.log('\nRUN VERDICT (canonical SQL): ' + (canonicalOk ? 'OK' : 'FAIL - canonical store is empty'));
    console.log(`  ${persons > 0 ? 'OK  ' : 'FAIL'} triage_persons      ${persons < 0 ? 'UNREADABLE' : persons}`);
    console.log(`  ${emails > 0 ? 'OK  ' : 'FAIL'} triage_email_cache  ${emails < 0 ? 'UNREADABLE' : emails}`);
    console.log('  The graph-derived checks below are NOT failures - they have no source:');
    for (const chk of VERDICT_CHECKS) {
      console.log(`  UNAVAILABLE ${chk.id.padEnd(20)} (needs Phase 2.5 enrichment; no graph engine)`);
    }
    _forensicWrite({
      event: 'run_verdict',
      ok: canonicalOk,
      mode: 'canonical-sql',
      persons,
      emails,
      graphChecksUnavailable: VERDICT_CHECKS.map(c => c.id),
    });
    if (!canonicalOk) process.exitCode = 3;
    return;
  }

  try {
    const { rawRead: _vRead } = _require('./lib/graph/graph-transport.js') as any;
    const scale = parseFloat(process.env.VERDICT_MIN_SCALE ?? '1');
    const results: Array<{ id: string; count: number; min: number; ok: boolean }> = [];
    for (const chk of VERDICT_CHECKS) {
      let count = -1; // -1 = unreadable (counts as failure, not as zero)
      try { const r = await _vRead(chk.cypher, {}); count = Number(r[0]?.n ?? 0); } catch { /* unreadable */ }
      const min = Math.max(1, Math.ceil(chk.min * scale));
      results.push({ id: chk.id, count, min, ok: count >= min });
    }
    const failed = results.filter(r => !r.ok);
    console.log('\nRUN VERDICT: ' + (failed.length === 0 ? 'OK' : `DEGRADED — ${failed.length}/${results.length} below threshold`));
    for (const r of results) console.log(`  ${r.ok ? 'OK  ' : 'FAIL'} ${r.id.padEnd(20)} ${r.count} (min ${r.min})`);
    _forensicWrite({ event: 'run_verdict', ok: failed.length === 0, results });
    if (failed.length > 0) process.exitCode = 3;
  } catch (e: any) {
    console.warn(`RUN VERDICT: could not compute — ${String(e?.message || '').slice(0, 80)}`);
    _forensicWrite({ event: 'run_verdict', ok: false, error: String(e?.message || '').slice(0, 120) });
    process.exitCode = 3;
  }
}


const PHASE3_CHECKPOINT_PATH = join(ELYNTIC_DATA_DIR, 'email-backfill-30d-phase3-checkpoint.json');
const INDEX_30D_PATH = join(DATA_DIR, 'gmail-index-30d.json');
const EXISTING_INDEX_PATH = join(DATA_DIR, 'gmail-index.json');
const TRIAGE_DIR = join(ELYNTIC_DATA_DIR, 'email-triage');

/**
 * Number of emails processed per orchestrator.run() invocation during Phase 3.
 * Smaller batches mean fewer concurrent Graph sessions, preventing pool exhaustion.
 * Override via PHASE3_CHUNK_SIZE env var (e.g. PHASE3_CHUNK_SIZE=100 for slow machines).
 * NX pattern: nx-vegas-limit.js â€” auto-adjusts batch size based on Graph memory pressure.
 * The health monitor reduces this at runtime when memory > 6.5 GiB.
 */
let PHASE3_CHUNK_SIZE = parseInt(process.env.PHASE3_CHUNK_SIZE ?? '200', 10);
const PHASE3_CHUNK_SIZE_MIN = parseInt(process.env.PHASE3_CHUNK_SIZE_MIN ?? '50', 10);
// MAX must be independent of the starting size — anchoring it to PHASE3_CHUNK_SIZE
// meant the health monitor could shrink the chunk but never recover it.
const PHASE3_CHUNK_SIZE_MAX = parseInt(process.env.PHASE3_CHUNK_SIZE_MAX ?? '1000', 10);

/**
 * Delay in ms between Phase 3 batch invocations.
 * Gives Graph GC time between bulk writes â€” mirrors bulkIngest's interBatchDelayMs.
 * Override via PHASE3_INTER_BATCH_DELAY_MS (e.g. 0 to disable).
 * NX pattern: health monitor increases this delay when Graph is under memory pressure.
 */
let PHASE3_INTER_BATCH_DELAY_MS = parseInt(process.env.PHASE3_INTER_BATCH_DELAY_MS ?? '2000', 10);

// NX pattern: nx-health-monitor.js â€” Graph memory pressure callbacks
// Wired here so the backfill automatically throttles when memory > 6.5 GiB
// and pauses key-facts queue when memory > 8.0 GiB.
// Source: .planning/extracted/nx-health-monitor.js
let _backfillHealthMonitor: any = null;
function _startBackfillHealthMonitor(): void {
  try {
    const { HealthMonitor } = (globalThis as any).__elyntic_health_monitor_class ??
      (() => { try { return require('./lib/broker/health-monitor.js'); } catch { return null; } })() ?? {};
    if (!HealthMonitor) return; // not available in all environments
    const { rawRead: _hmRead, rawWrite: _hmWrite, rawWriteEmergency: _hmEmergency } =
      require('./lib/graph/graph-transport.js') as any;
    _backfillHealthMonitor = new HealthMonitor(_hmRead, _hmWrite, {
      emergencyWriteFn: _hmEmergency ?? _hmWrite,
      onVegasBackoff: () => {
        // Memory > 6.5 GiB â€” shrink batch size to reduce Graph write load
        const before = PHASE3_CHUNK_SIZE;
        PHASE3_CHUNK_SIZE = Math.max(PHASE3_CHUNK_SIZE_MIN, Math.floor(PHASE3_CHUNK_SIZE * 0.75));
        if (PHASE3_CHUNK_SIZE < before) {
          process.stderr.write(`[backfill-health] Memory pressure â€” chunk size ${before}â†’${PHASE3_CHUNK_SIZE}, delay +1s\n`);
          PHASE3_INTER_BATCH_DELAY_MS += 1000;
        }
      },
      onMagePause: () => {
        // Memory > 8.0 GiB â€” pause key-facts Qwen3 queue to free RAM
        process.stderr.write('[backfill-health] Memory critical (>8GiB) â€” pausing Qwen3 key-facts queue\n');
        try {
          const { factQueue } = require('./lib/triage-core/mental-model/fact-extraction-queue.ts') as any;
          factQueue?._paused !== undefined && (factQueue._paused = true);
        } catch { /* non-fatal */ }
      },
      onMageResume: () => {
        // Memory < 6.4 GiB â€” restore batch size and resume key-facts
        if (PHASE3_CHUNK_SIZE < PHASE3_CHUNK_SIZE_MAX) {
          PHASE3_CHUNK_SIZE = Math.min(PHASE3_CHUNK_SIZE_MAX, Math.floor(PHASE3_CHUNK_SIZE * 1.25));
          PHASE3_INTER_BATCH_DELAY_MS = Math.max(2000, PHASE3_INTER_BATCH_DELAY_MS - 1000);
          process.stderr.write(`[backfill-health] Memory recovered â€” chunk size restored to ${PHASE3_CHUNK_SIZE}\n`);
        }
        try {
          const { factQueue } = require('./lib/triage-core/mental-model/fact-extraction-queue.ts') as any;
          factQueue?._paused !== undefined && (factQueue._paused = false);
        } catch { /* non-fatal */ }
      },
    });
    _backfillHealthMonitor.start();
    process.stderr.write('[backfill-health] Memory health monitor started\n');
  } catch { /* non-fatal â€” health monitor is an optional enhancement */ }
}


// ---------------------------------------------------------------------------
// CLI argument parsing
// ---------------------------------------------------------------------------

function parseArgs(): {
  account: string;
  since: Date;
  until: Date;
  limit: number;
  dryRun: boolean;
  reset: boolean;
  resetPhase3: boolean;
  offline: boolean;
  skipDrafts: boolean;
  skipEnrichment: boolean;
  enrichmentOnly: boolean;
  skipChannels: boolean;
  skipOrg: boolean;
  maxCost: number | null;
  force: boolean;
} {
  const args = process.argv.slice(2);

  // --help
  if (args.includes('--help') || args.includes('-h')) {
    console.log(`
Elyntic internal email backfill worker

Usage:
  Use run-backfill-30d.ts or POST /api/email/triage/backfill.

Options:
  --since <value>       Start of time window. Default: 90d
                        Relative: 30d, 7d, 1w, 2h, 1h, 30m
                        Absolute: 2026-05-01 or ISO string
  --until <value>       End of time window. Default: now
  --account <id>        Gmail account id. Default: primary
  --limit <n>           Max messages to process. Default: unlimited
  --dry-run             Print config and exit without fetching
  --force-phase1        Force a live Gmail re-fetch even if local index is fresh
  --offline             Skip live Gmail API; use cached index
  --skip-enrichment     Skip Phase 2.5 (FAVEE/Dunbar/PageRank/etc). Fast daily path â€”
                        syncs new emails and runs triage without recomputing all signals.
                        Use this for runs triggered throughout the day.
  --enrichment-only     Skip Phase 1 (Gmail sync), Phase 2 (graph ingest), and Phase 3
                        (triage). Runs only Phase 2.5 enrichment on the current graph.
                        Use this for the nightly scheduled enrichment job.
   --skip-drafts         Skip LLM auto-draft generation for P0/P1 items.
                        Saves ~30-40% of backfill cost. Recommended for
                        frequent intraday runs.
  --skip-channels       Skip Phase 1b (iMessage) channel fetch.
                        Gmail Phase 1a is unaffected. Use for Gmail-only runs.
  --skip-org            Skip Phase 5 organization mapping (domain classifier + LLM
                        KeyFact extraction). Use for fast runs without org enrichment.
  --max-cost <usd>      Forward-looking hard cap on estimated cloud draft cost.
                        Aborts before Phase 3 if the estimate (priced at the
                        configured provider's list rates) exceeds this. Advisory
                        only when omitted. NOTE: drafting currently runs LOCALLY,
                        so real spend today is ~$0 regardless of provider.
  --force               Override the --max-cost cap and run anyway.
  --help                Show this help

Recommended schedule:
  Throughout the day  â€” npx tsx run-backfill-30d.ts --account <id> --skip-enrichment --skip-channels
  Nightly (2am)       â€” npx tsx run-backfill-30d.ts --account <id> --enrichment-only
  Weekly (Sunday)     â€” npx tsx run-backfill-30d.ts --account <id> --since 90d
  First run/bootstrap â€” npx tsx run-backfill-30d.ts --account <id> --since 90d

Note: Phase 1 (Gmail delta sync) runs automatically on every invocation and pulls only
      new emails since the last run via historyId. Use --force-phase1 to re-fetch all.
`.trim());
    process.exit(0);
  }

  const accountIdx = args.indexOf('--account');
  // If --account not specified, use the configured default account (from accounts.json)
  // rather than hardcoding 'primary' which may not match any account ID.
  const accountArg = accountIdx !== -1 ? args[accountIdx + 1] : null;

  const sinceIdx = args.indexOf('--since');
  const sinceArg = sinceIdx !== -1 ? args[sinceIdx + 1] : '90d';

  const untilIdx = args.indexOf('--until');
  const untilArg = untilIdx !== -1 ? args[untilIdx + 1] : null;

  const limitIdx = args.indexOf('--limit');
  // Default: no limit â€” fetch ALL emails in the time window.
  // Deduplication (skipDedup=false) means already-processed emails are skipped
  // automatically via Graph rawId lookup, so re-running is always safe.
  const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : Number.MAX_SAFE_INTEGER;

  const dryRun = args.includes('--dry-run');
  const skipDrafts = args.includes('--skip-drafts');
  const reset = args.includes('--reset');
  const resetPhase3 = args.includes('--phase3-reset');
  const offline = args.includes('--offline');
  // --skip-enrichment: fast daily path â€” sync + triage, skip Phase 2.5 (FAVEE/Dunbar/PageRank etc)
  const skipEnrichment = args.includes('--skip-enrichment');
  // --enrichment-only: nightly batch â€” skip sync + triage, run only Phase 2.5 enrichment
  const enrichmentOnly = args.includes('--enrichment-only');
  // WS6 canary: one stratified contact sample shared by all per-contact loops.
  const _sampleIdx = args.indexOf('--sample');
  if (_sampleIdx !== -1) {
    const _sampleN = parseInt(args[_sampleIdx + 1] || '150', 10) || 150;
    process.env.BACKFILL_SAMPLE_LIMIT = String(_sampleN);
    process.env.T35_ROLE_FAVEE_LIMIT = process.env.T35_ROLE_FAVEE_LIMIT ?? String(_sampleN);
    // Verdict thresholds scale to the sample (counts are graph-cumulative, so
    // this only matters on fresh/reset graphs — documented limitation).
    process.env.VERDICT_MIN_SCALE = process.env.VERDICT_MIN_SCALE ?? String(Math.min(1, _sampleN / 2000));
  }
  if (args.includes('--stress')) {
    // Compress time-dependent failure modes: same contention ratio as hours
    // of full load, in a 30-minute window.
    process.env.GRAPH_QUERY_SEMAPHORE_SIZE = '4';
  }
  // --skip-channels: skip Phase 1b (iMessage) â€” Gmail fetch unaffected
  const skipChannels = args.includes('--skip-channels');
  // --skip-org: skip Phase 5 organization mapping
  const skipOrg = args.includes('--skip-org');

  // --max-cost <usd>: forward-looking hard cap. If the estimated cloud draft cost
  // (priced at provider list rates) exceeds this, the run aborts before Phase 3
  // unless --force is also passed. Null = no cap (advisory estimate only).
  const maxCostIdx = args.indexOf('--max-cost');
  const maxCost = maxCostIdx !== -1 ? parseFloat(args[maxCostIdx + 1]) : null;
  // --force: override the --max-cost cap.
  const force = args.includes('--force');

  const since = parseSince(sinceArg);
  const until = untilArg ? parseSince(untilArg) : new Date();

  // Resolve the account ID: use --account arg, or fall back to the configured default account.
  // If the arg looks like an email address (contains '@'), match on AccountConfig.email first
  // so callers can pass --account owner@example.com without knowing the internal ID.
  let account: string;
  if (accountArg) {
    // Preserve provider email identities exactly. Converting an email to a
    // company-scoped account id is ambiguous when one company has two inboxes.
    account = accountArg;
  } else {
    account = getDefaultAccount()?.id ?? 'default';
  }

  return { account, since, until, limit, dryRun, reset, resetPhase3, offline, skipDrafts, skipEnrichment, enrichmentOnly, skipChannels, skipOrg, maxCost, force };
}


// ---------------------------------------------------------------------------
// Forward-looking cloud-provider cost gate (advisory + optional hard cap)
// ---------------------------------------------------------------------------
// IMPORTANT HONESTY NOTE: The backfill's draft path currently runs LOCALLY
// (extensions/email/actions/draft-response.ts drives a local Qwen GGUF via
// Ollama — no cloud API call is made). So this gate does NOT measure real
// spend. It is a FORWARD-LOOKING, rate-based guardrail that prices the draft
// phase at the configured cloud provider's public list rates, for the day the
// draft path is repointed at a paid provider. With drafting local, real spend
// today is ~$0. Every line below says so.

// ELYNTIC_PROVIDER → estimator key mapping lives in
// lib/triage-core/backfill-cost-estimator.ts (providerTypeForEstimator).

// Advisory cost estimate + optional hard cap. Throws (aborting before Phase 3)
// when the forward-looking estimate exceeds --max-cost and --force is absent.
function costGate(
  emailCount: number,
  opts: { skipDrafts: boolean; maxCost: number | null; force: boolean },
): void {
  const type = providerTypeForEstimator(process.env.ELYNTIC_PROVIDER);

  // Local / bundled runner: no metered API cost, so there is nothing to gate.
  if (type === 'local' || type === 'ollama') {
    console.log(`\nCost gate: provider is local (ELYNTIC_PROVIDER=${process.env.ELYNTIC_PROVIDER || '<unset>'}) — drafting runs on the bundled/local model, so there is no metered cloud cost. Skipping cost gate.`);
    return;
  }

  // The estimator uses ONLY emails.length; subject/snippet are ignored, so a
  // count-shaped array of empty objects yields an identical estimate.
  const est = estimateBackfillCost(
    Array.from({ length: emailCount }, () => ({})) as any,
    { type },
    !opts.skipDrafts,
  );
  const draftableEmails = opts.skipDrafts ? 0 : Math.ceil(emailCount * 0.3);

  console.log('\n── Forward-looking cloud cost estimate (advisory) ──────────────────');
  console.log(`  provider           : ${type} (${est.phases.drafts.model})`);
  console.log(`  emails in scope    : ${emailCount}`);
  console.log(`  draftable (~30%)   : ${draftableEmails}${opts.skipDrafts ? ' (--skip-drafts: drafts off)' : ''}`);
  console.log(`  est. draft cost    : $${est.totalEstimatedCostUSD.toFixed(2)} (extraction is always $0.00 — bundled model)`);
  console.log(`  est. wall time     : ~${est.totalEstimatedMinutes} min`);
  console.log('  NOTE: This prices the draft phase at ' + type + ' public list rates as a');
  console.log('        FORWARD-LOOKING guardrail. Backfill drafting currently runs LOCALLY');
  console.log('        (local Qwen via Ollama), so real spend today is ~$0. This is NOT a');
  console.log('        measurement of actual current cloud spend.');
  console.log('────────────────────────────────────────────────────────────────────');

  if (opts.maxCost != null && est.totalEstimatedCostUSD > opts.maxCost && !opts.force) {
    throw new Error(
      `Cost gate: forward-looking estimate $${est.totalEstimatedCostUSD.toFixed(2)} exceeds --max-cost $${opts.maxCost.toFixed(2)} ` +
      `(priced at ${type} list rates; drafting currently runs locally so real spend today is ~$0). ` +
      `Re-run with a higher --max-cost, or --force to override this cap.`,
    );
  }
}



// ---------------------------------------------------------------------------
// Check if Gmail token is still valid (not expired)
// ---------------------------------------------------------------------------
// ensureTokenFresh: attempts to refresh the token if expired, returns true if a valid
// access token is available after the attempt. Never blocks the live path due to expiry.
// replaces the old isTokenFresh() check which would silently fall to offline mode on expiry.
async function ensureTokenFresh(tokenPath: string): Promise<boolean> {
  try {
    const resolved = resolveTokenPath(tokenPath);
    if (!existsSync(resolved)) return false;
    const token = JSON.parse(readFileSync(resolved, 'utf-8'));
    if (!token.refresh_token) return false;
    // refreshAccessToken is idempotent â€” no-ops if still valid, refreshes if expired, saves result
    await refreshAccessToken(resolved);
    return true;
  } catch (e: any) {
    const msg = String(e?.message ?? e);
    // invalid_client means the OAuth client registration was deleted or rotated in Google Cloud Console.
    // The stored token's client_id no longer exists â€” re-authorization is required.
    // Ref: https://developers.google.com/identity/protocols/oauth2/web-server#error-codes
    // Fix: re-run account setup: npx tsx scripts/setup-email.ts --account <id>
    if (msg.includes('invalid_client') || msg.includes('client was not found')) {
      process.stderr.write(
        `[backfill] OAuth client not found â€” the stored token's client_id has been deleted or rotated.\n` +
        `  Fix: re-authorize the account: npx tsx scripts/setup-email.ts --account ${resolveTokenPath(tokenPath)}\n` +
        `  Or restore the OAuth client in Google Cloud Console: https://console.developers.google.com/auth/clients\n`
      );
    } else {
      process.stderr.write(`[backfill] token refresh failed: ${msg}\n`);
    }
    return false;
  }
}

// ---------------------------------------------------------------------------
// Phase 1: Fetch/build 30-day Gmail index â†’ gmail-index-30d.json
// ---------------------------------------------------------------------------
async function phase1FetchGmailIndex(opts: {
  account: ReturnType<typeof getAccount>;
  since: Date;
  until: Date;
  limit: number;
  dryRun: boolean;
  offline: boolean;
  reset?: boolean;
  skipDrafts?: boolean;
}): Promise<void> {
  const { account, since, until, limit, dryRun, offline, reset = false } = opts;
  console.log(`\nPhase 1/4: Building 30-day Gmail index...`);
  sendIPC({ type: 'phase', ts: Date.now(), phase: '1a', label: 'Gmail fetch', state: 'running' });
  console.log(`  Account: ${account!.email}`);
  console.log(`  Since: ${since.toISOString()}`);
  console.log(`  Until: ${until.toISOString()}`);
  console.log(`  Limit: ${limit}`);

  if (dryRun) {
    console.log('  [dry-run] skipping Gmail fetch');
    return;
  }

  // Determine whether to use live API or filter existing index
  // ensureTokenFresh() refreshes in-process if expired â€” no manual pre-run needed
  const tokenPath = resolveTokenPath(account!.tokenPath);
  const tokenFresh = !offline && await ensureTokenFresh(tokenPath);

  let messages: any[] = [];

  if (tokenFresh) {
    // â”€â”€ Live path: call Gmail API â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    console.log('  Token is fresh â€” fetching live from Gmail API...');
    try {
      const provider = new GmailProvider({ account: account! });

      // fetchAllInbox is a proper typed method on GmailProvider â€” no duck-typing needed.
      if (typeof provider.fetchAllInbox === 'function') {
        console.log('  Using fetchAllInbox (full message mode)...');

        // â”€â”€ Phase 1 checkpoint: resume from SQL (primary) or JSON file (fallback) â”€â”€
        // Dual-store: SQL survives Graph outages; JSON file survives DB corruption.
        const PHASE1_PARTIAL_PATH = join(DATA_DIR, 'gmail-index-partial.json');
        const accountId = emailCacheAccountId(account);
        const sinceWindow = since.toISOString();
        let resumedMessages: any[] = [];
        let resumeFromCount = 0;
        let cachedIdSet: Set<string> | null = null;

        if (!reset) {
          // Primary: try SQL cache (lightweight messageId-only query to prevent V8 OOM)
          try {
            cachedIdSet = loadEmailCacheMessageIds(accountId, sinceWindow);
            if (cachedIdSet && cachedIdSet.size > 0) {
              resumeFromCount = cachedIdSet.size;
              console.log(`  Resuming from SQL cache: ${resumeFromCount} messages already fetched`);
            }
          } catch { /* SQL unavailable — fall through to JSON */ }

          // Fallback: JSON partial checkpoint file
          if (resumeFromCount === 0 && existsSync(PHASE1_PARTIAL_PATH)) {
            try {
              const partial = readEmailCheckpointFile(PHASE1_PARTIAL_PATH);
              if (partial.since === sinceWindow && Array.isArray(partial.messages) && partial.messages.length > 0) {
                resumedMessages = COORDINATED_FETCH
                  ? materializeCoordinatedEmailAttachments(
                      admittedBackfillMessages(
                        partial.messages,
                        since,
                        until,
                        'JSON resume checkpoint',
                      ),
                    )
                  : partial.messages;
                resumeFromCount = resumedMessages.length;
                console.log(`  Resuming from JSON checkpoint: ${resumeFromCount} messages already fetched`);
                // Back-fill SQL from JSON checkpoint so next resume uses SQL
                upsertEmailCacheBatch(resumedMessages, accountId, sinceWindow);
              }
            } catch (err) { throw err; }
          }
        } else {
          // --reset: clear both stores
          try { clearEmailCache(accountId, sinceWindow); } catch { /* non-fatal */ }
        }

        let lastLoggedCount = resumeFromCount;
        let lastSavedCount = resumeFromCount;

        // BUG-9 FIX: accumulate live-fetched messages for mid-run checkpoints.
        // Previously onProgress wrote `resumedMessages` (the pre-run cache, never updated
        // during the fetch) so all partial checkpoint files contained stale/empty data.
        // Fix: maintain a live accumulator that grows as messages arrive, so that if the
        // fetch throws mid-way (e.g. quota error) the partial file contains real data.
        const liveAccumulated: any[] = [...resumedMessages];

        const fetchStartedAt = new Date().toISOString();
        const fetchStartedMs = Date.parse(fetchStartedAt);
        const fetchResult = await provider.fetchAllInbox({
          since,
          until,
          maxResults: limit,
          includeAttachmentData: COORDINATED_FETCH,
          // Pass cached IDs so provider skips re-fetching bodies for already-downloaded messages
          // Docs (2026-06-03): "use format=MINIMAL for previously cached messages — only labelIds may change"
          cachedIds: resumeFromCount > 0 ? (cachedIdSet && cachedIdSet.size > 0 ? cachedIdSet : new Set(resumedMessages.map((m: any) => m.messageId))) : undefined,
          onProgress: (count: number, newBatch?: any[], failedCount = 0) => {
            // Provider awaits this callback before advancing its page token.
            // Commit every page before acknowledging progress, even below the
            // 500-message JSON checkpoint interval.
            if (newBatch && Array.isArray(newBatch)) {
              const admittedBatch = COORDINATED_FETCH
                ? materializeCoordinatedEmailAttachments(
                    admittedBackfillMessages(newBatch, since, until, 'Gmail fetch page'),
                  )
                : newBatch;
              upsertEmailCacheBatch(admittedBatch, accountId, sinceWindow);
              liveAccumulated.push(...admittedBatch);
            }
            const total = resumeFromCount + count;
            const settled = resumeFromCount + count + failedCount;
            const progressAt = new Date().toISOString();
            emitCoordinatorProgress({
              stageKey: 'fetch_messages',
              stageLabel: 'Fetch Gmail messages',
              completed: settled,
              knownTotal: false,
              active: 1,
              failed: failedCount,
              startedAt: fetchStartedAt,
              progressAt,
              elapsedMs: Math.max(0, Date.parse(progressAt) - fetchStartedMs),
            });
            if (total >= lastLoggedCount + 50) {
              process.stdout.write(`\r  Progress: ${total} messages fetched...`);
              lastLoggedCount = total;
            }
            // JSON is a recovery copy of pages already committed to SQL.
            if (count - (lastSavedCount - resumeFromCount) >= 500) {
              mkdirSync(DATA_DIR, { recursive: true });
              const checkpointSlice = liveAccumulated.slice(-1000);
              writeJsonArrayFile(PHASE1_PARTIAL_PATH, checkpointSlice, {
                since: sinceWindow, until: until.toISOString(),
                savedAt: new Date().toISOString(),
              });
              lastSavedCount = resumeFromCount + count;
              if (liveAccumulated.length > 2000) {
                liveAccumulated.splice(0, liveAccumulated.length - 1000);
              }
            }
          },
        });

        // Merge resumed messages with newly fetched (deduplicate by messageId)
        const fetchedNew: any[] = COORDINATED_FETCH
          ? materializeCoordinatedEmailAttachments(
              admittedBackfillMessages(fetchResult, since, until, 'Gmail fetch result'),
            )
          : fetchResult;
        if (resumeFromCount > 0) {
          const existingIds = new Set(resumedMessages.map((m: any) => m.messageId));
          const dedupedNew = fetchedNew.filter((m: any) => !existingIds.has(m.messageId));
          messages = COORDINATED_FETCH
            ? admittedBackfillMessages(
                [...resumedMessages, ...dedupedNew],
                since,
                until,
                'merged Gmail result',
              )
            : [...resumedMessages, ...dedupedNew];
          console.log(`  Merged: ${resumeFromCount} resumed + ${dedupedNew.length} new = ${messages.length} total`);
        } else {
          messages = fetchedNew;
        }

        if (lastLoggedCount > 0) process.stdout.write('\n');
        console.log(`  fetchAllInbox returned ${messages.length} messages`);
        upsertEmailCacheBatch(messages, accountId, sinceWindow);
        const fetchCompletedAt = new Date().toISOString();
        const fetchFailedCount = (fetchResult as any).failedCount ?? 0;
        const fetchAttemptedCount = messages.length + fetchFailedCount;
        emitCoordinatorProgress({
          stageKey: 'fetch_messages',
          stageLabel: 'Fetch Gmail messages',
          completed: fetchAttemptedCount,
          total: fetchAttemptedCount,
          knownTotal: true,
          active: 0,
          failed: fetchFailedCount,
          startedAt: fetchStartedAt,
          progressAt: fetchCompletedAt,
          elapsedMs: Math.max(0, Date.parse(fetchCompletedAt) - fetchStartedMs),
        });

        // â”€â”€ Dual-store the complete fetched result â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
        // SQL: upsert all messages so resume works even if JSON file is lost
        console.log(`  âœ“ Email cache saved to SQL (${messages.length} messages)`);
        // Clear partial JSON checkpoint now that we have the full result in SQL
        try { if (existsSync(PHASE1_PARTIAL_PATH)) { const { unlinkSync } = await import('node:fs'); unlinkSync(PHASE1_PARTIAL_PATH); } } catch { /* non-fatal */ }

        // Save historyId anchor for incremental sync on next run
        if ((fetchResult as any).lastHistoryId) {
          process.stdout.write(`  historyId anchor: ${(fetchResult as any).lastHistoryId}\n`);
          (opts as any)._lastHistoryId = (fetchResult as any).lastHistoryId;
        }
      } else {
        // Fallback to fetchAll (includes body)
        console.log('  Using fetchAll (includes body)...');
        const emails = await provider.fetchAll(since, limit, until);
        messages = emails.map(e => ({
          messageId: e.id,
          threadId: (e as any).threadId || e.id,
          from: e.from,
          to: Array.isArray(e.to) ? e.to : [e.to].filter(Boolean),
          cc: [],
          subject: e.subject,
          date: e.date,
          snippet: (e.body || '').slice(0, 200),
          labels: e.labels || [],
        }));
      }
    } catch (err: any) {
      // A failed fetch/persistence callback must not become successful offline
      // completion, in either coordinated or standalone mode.
      throw err;
    }
  }

  // â”€â”€ Offline/fallback path: SQL cache â†’ JSON checkpoint â†’ existing index â”€â”€â”€â”€
  if (!tokenFresh || messages.length === 0) {
    const accountId = emailCacheAccountId(account);
    const sinceWindow = since.toISOString();

    // Priority 1: SQL cache (most reliable â€” survives JSON file loss)
    if (!reset) {
      try {
        const sqlCached = loadEmailCache(accountId, sinceWindow);
        if (sqlCached && sqlCached.length > 0) {
          console.log(`  Using SQL cache: ${sqlCached.length} messages for ${accountId} since ${sinceWindow}`);
          console.log('  Token expired â€” refresh token and re-run without --reset to fetch remaining messages');
          messages = COORDINATED_FETCH
            ? materializeCoordinatedEmailAttachments(
                admittedBackfillMessages(sqlCached, since, until, 'offline SQL cache'),
              )
            : sqlCached;
        }
      } catch { /* SQL unavailable â€” fall through */ }
    }

    // Priority 2: JSON partial checkpoint file (fallback if SQL unavailable)
    const PHASE1_PARTIAL_PATH = join(DATA_DIR, 'gmail-index-partial.json');
    if (messages.length === 0 && !reset && existsSync(PHASE1_PARTIAL_PATH)) {
      try {
        const partial = readEmailCheckpointFile(PHASE1_PARTIAL_PATH);
        if (Array.isArray(partial.messages) && partial.messages.length > 0) {
          console.log(`  Using JSON checkpoint: ${partial.messages.length} messages (saved ${partial.savedAt})`);
          console.log('  Token expired â€” refresh token and re-run without --reset to fetch remaining messages');
          messages = COORDINATED_FETCH
            ? materializeCoordinatedEmailAttachments(
                admittedBackfillMessages(
                  partial.messages,
                  since,
                  until,
                  'offline JSON checkpoint',
                ),
              )
            : partial.messages;
        }
      } catch { /* corrupt checkpoint */ }
    }  // end JSON checkpoint

    if (messages.length === 0) {
      // Priority 3: existing full gmail-index.json (date-filtered)
      if (!existsSync(EXISTING_INDEX_PATH)) {
        console.error(`  FATAL: No cached messages available (SQL cache empty, no JSON checkpoint, no existing index).`);
        console.error(`  Refresh your Gmail token and re-run, or use --reset to start fresh.`);
        process.exit(1);
      }

    console.log(`  Using existing gmail-index.json (filtering since ${since.toISOString()})...`);
    const allMessages = [...iterateJsonArrayFile(EXISTING_INDEX_PATH)];
    const sinceMs = since.getTime();
    const untilMs = until.getTime();
    let parsed = 0, skipped = 0;

    messages = (COORDINATED_FETCH
      ? admittedBackfillMessages(allMessages, since, until, 'existing Gmail index')
      : allMessages.filter((m: any) => {
      if (!m.date) { skipped++; return false; }
      try {
        const d = new Date(m.date);
        if (!isNaN(d.getTime()) && d.getTime() >= sinceMs && d.getTime() <= untilMs) { parsed++; return true; }
        // Try RFC 2822 parse
        const d2 = new Date(m.date.replace(/^\w+,\s*/, '').trim());
        if (!isNaN(d2.getTime()) && d2.getTime() >= sinceMs && d2.getTime() <= untilMs) { parsed++; return true; }
        skipped++;
        return false;
      } catch { skipped++; return false; }
      })).slice(0, limit);

    console.log(`  Filtered: ${messages.length} messages in range (${skipped} outside range)`);
    } // end if (messages.length === 0)
  }

  if (messages.length === 0) {
    console.log('  WARNING: No messages found in date range.');
  }

  // â”€â”€ Pass 2: fetch full body for urgent candidates â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Legal/financial keywords in subject/snippet trigger a full-body fetch so
  // all 29 triage signals get complete body content (not a 200-char snippet).
  if (tokenFresh) {
    const URGENT_PATTERNS = /lien|subpoena|overdue|collections|legal notice|cease|default|overdraft|payment due|final notice|eviction|demand letter|case\s*#|nonpayment|enforcement/i;
    const urgentItems = messages.filter((m: any) =>
      URGENT_PATTERNS.test(m.subject || '') || URGENT_PATTERNS.test(m.snippet || '')
    );
    if (urgentItems.length > 0) {
      const provider2 = new GmailProvider({ account: account! });
      console.log(`  Pass 2: Fetching full bodies for ${urgentItems.length} urgent messages (concurrency=10)...`);
      // Cap at 10 concurrent Gmail API calls â€” prevents socket buffer exhaustion and
      // Gmail quota spikes when hundreds of legal/financial emails match.
      const FETCH_CONCURRENCY = 10;
      let bodyCount = 0;
      for (let fi = 0; fi < urgentItems.length; fi += FETCH_CONCURRENCY) {
        const batch = urgentItems.slice(fi, fi + FETCH_CONCURRENCY);
        const bodies = await Promise.allSettled(
          batch.map((m: any) => provider2.fetchById(m.messageId))
        );
        bodies.forEach((result, i) => {
          if (result.status === 'fulfilled' && result.value?.body) {
            batch[i].body = result.value.body;
            bodyCount++;
          }
        });
      }
      console.log(`  âœ“ Pass 2: Retrieved ${bodyCount}/${urgentItems.length} urgent email bodies`);
    }
  }

  mkdirSync(DATA_DIR, { recursive: true });
  if (COORDINATED_FETCH) {
    messages = materializeCoordinatedEmailAttachments(
      admittedBackfillMessages(messages, since, until, 'final Gmail index'),
    );
  }
  // All paths, including offline and legacy fetchAll, require SQL durability
  // before publishing the index, completion checkpoint, or history anchor.
  upsertEmailCacheBatch(messages, emailCacheAccountId(account), since.toISOString());
  writeJsonArrayFile(INDEX_30D_PATH, messages);
  console.log(`  âœ“ Saved ${messages.length} messages â†’ ${INDEX_30D_PATH}`);

  // Print sample
  const sample = messages.find((m: any) => m.from || m.messageId);
  if (sample) {
    const from = (sample.from || sample.messageId || '').substring(0, 60);
    const subject = (sample.subject || '').substring(0, 60);
    console.log(`  Sample: from="${from}" subject="${subject}"`);
  }

  saveCheckpoint(CHECKPOINT_PATH, {
    lastKey: 'phase1_complete',
    processed: messages.length,
    phase1MessagesCount: messages.length,
    phase1CompletedAt: new Date().toISOString(),
    indexPath: INDEX_30D_PATH,
    source: tokenFresh ? 'live_api' : 'existing_index',
    lastHistoryId: (opts as any)._lastHistoryId ?? null,
  });

  // Persist historyId to dedicated file so delta sync works on next run
  // independently of the main checkpoint lifecycle.
  const lastHistoryId = (opts as any)._lastHistoryId;
  if (lastHistoryId && !COORDINATED_FETCH) {
    const historyIdPath = join(ELYNTIC_DATA_DIR, 'phase1-history.json');
    try {
      writeFileSync(historyIdPath, JSON.stringify({ historyId: lastHistoryId, updatedAt: new Date().toISOString() }));
    } catch { /* non-fatal */ }
  }
}

// ---------------------------------------------------------------------------
// Phase 2: Ingest gmail-index-30d.json â†’ Graph
// ---------------------------------------------------------------------------
async function phase2IngestToGraph(dryRun: boolean, _accountEmail?: string, _sinceWindow?: string): Promise<void> {
  // Derive the normalized SQL cache key â€” same normalization as ingestEmailIndex uses internally
  const _p2sqlKey = COORDINATED ? coordinatedIdentity().providerAccountId
    : (_accountEmail?.includes('@') ? _accountEmail.split('@')[0] : _accountEmail);
  // BACKFILL-GRAPH-SWEEP-1: there is no "Graph only (no accountId)" mode
  // any more. Without an account key there is no canonical destination, and
  // ingestEmailIndex now refuses rather than writing to a graph instead.
  const _p2sqlMode = _p2sqlKey ? `canonical SQL (account="${_p2sqlKey}")` : 'NO DESTINATION (no accountId)';
  console.log(`\nPhase 2/4: Ingesting email index -> ${_p2sqlMode}...`);
  sendIPC({ type: 'phase', ts: Date.now(), phase: '2', label: 'Canonical ingest', state: 'running' });

  if (dryRun) {
    console.log('  [dry-run] skipping graph ingestion');
    return;
  }

  if (!existsSync(INDEX_30D_PATH)) {
    console.log(`  WARNING: ${INDEX_30D_PATH} not found â€” skipping graph ingestion`);
    return;
  }

  // BACKFILL-GRAPH-SWEEP-1: removed the Graph storage tuning that ran
  // here (SET DATABASE SETTING 'storage.access_timeout_sec', plus the
  // gc-aggressive reasoning above it). Every one of those settings existed to
  // survive the delta accumulation caused by writing 10K+ nodes and edges into
  // Graph during this phase. The phase no longer writes to Graph, so the
  // pressure they relieved does not exist, and the calls were pure connection
  // attempts. SQLite needs no equivalent: the ingest batches inside explicit
  // transactions and the WAL/busy_timeout pragmas are set once in _getDb().

  // Clear the ingestEmailIndex checkpoint so it processes the full 30d index from scratch.
  // IMPORTANT: backfill.ts writes its checkpoint to EMAIL_BACKFILL_CHECKPOINT_PATH
  // (~/helios-agent/data/email-backfill-checkpoint.json), NOT to ELYNTIC_DATA_DIR.
  // Clear both paths to avoid stale checkpoints from either location.
  for (const cpPath of [EMAIL_BACKFILL_CHECKPOINT_PATH, join(ELYNTIC_DATA_DIR, 'email-backfill-checkpoint.json')]) {
    if (existsSync(cpPath)) {
      clearCheckpoint(cpPath);
      console.log(`  Cleared ingest checkpoint: ${cpPath}`);
    }
  }

  // W7: read the store BEFORE the phase. Without the before-count there is
  // nothing to compare against, and "10096 created" stays unfalsifiable.
  // BACKFILL-GRAPH-SWEEP-1: before/after counts now come from canonical SQL.
  // Counting graph nodes after a phase that writes SQL would measure a store
  // this phase no longer touches - reporting NO_ROWS_LANDED on a successful
  // run, or (with a stale Graph still up) reporting healthy counts produced
  // by some entirely different write. The W7 discipline is unchanged: read
  // before, read after, refuse a phase that submitted work and landed nothing.
  const _before = readCanonicalPersonCount();

  const result = await ingestEmailIndex(INDEX_30D_PATH, _accountEmail, _sinceWindow);
  if (result.errors.length > 0) {
    throw new Error(`Canonical email ingest failed: ${result.errors.length} error(s)`);
  }

  // Health stats were graph-transport's dropped-query and abandoned-session
  // counters. There is no graph in this phase, so there is no such pressure to
  // report; these zeroes are structural, not measured, and are kept only
  // because assessPhasePersistence takes the shape.
  const mgP2Health = { droppedQueries: 0, abandonedSessions: 0 };

  console.log(`  âœ“ Emails created/merged: ${result.emailsCreated}`);
  sendIPC({ type: 'metric', ts: Date.now(), key: 'emails', value: result.emailsCreated });
  sendIPC({ type: 'metric', ts: Date.now(), key: 'persons', value: result.personsCreated });
  sendIPC({ type: 'metric', ts: Date.now(), key: 'edges', value: result.edgesCreated });
  sendIPC({ type: 'phase', ts: Date.now(), phase: '2', label: 'Canonical ingest', state: 'done' });
  // personsCreated is now a READBACK count (rows verified present after the
  // write), not a submission count. The old caveat about MERGE submissions
  // no longer applies, because the readback IS the store count.
  console.log(`  âœ“ Persons verified present: ${result.personsCreated}`);
  console.log(`  âœ“ Correspondence links: ${result.edgesCreated}`);
  console.log(`  âœ“ Duration: ${result.duration}ms`);
  if (result.errors.length > 0) {
    console.log(`  âš  ${result.errors.length} chunk error(s) (first: ${result.errors[0]})`);
  }
  // BACKFILL-GRAPH-SWEEP-1: removed the Graph-pressure report. It warned
  // about dropped queries and abandoned sessions during graph writes, and told
  // the operator that Phase 2.5 T0-A would fill the gaps via MERGE. Neither the
  // pressure nor that recovery path exists now, so keeping the branch would
  // have printed a permanently unreachable reassurance.


  // W7: read the store back and record what actually landed. The 2026-07-11 run
  // wrote phase2PersonsCreated:10096 / phase2Errors:0 / phase4CompletedAt and
  // persisted nothing, because no branch here could ever fail.
  const _after = readCanonicalPersonCount();
  const _verdict = assessPhasePersistence({
    submitted: result.personsCreated,
    storeCountBefore: _before.count,
    storeCountAfter: _after.count,
    storeReadError: _after.error,
    chunkErrors: result.errors.length,
    health: mgP2Health,
  });
  console.log(`  ${_verdict.ok ? 'âœ“' : 'âœ—'} Persistence: ${_verdict.status} â€” canonical SQL holds ${_verdict.storeCountAfter ?? 'UNKNOWN'} person row(s) after (delta ${_verdict.landedDelta ?? 'UNKNOWN'}), ${_verdict.effectiveErrors} effective error(s)`);
  for (const r of _verdict.reasons) console.log(`      ${r}`);

  saveCheckpoint(CHECKPOINT_PATH, {
    lastKey: 'phase2_complete',
    phase2EmailsCreated: result.emailsCreated,
    // Kept for existing readers (the summary printer reads this key). It counts
    // items SUBMITTED to MERGE, which is why the truthful keys sit beside it.
    phase2PersonsCreated: result.personsCreated,
    phase2EdgesCreated: result.edgesCreated,
    // Now includes Graph-level drops, not just chunk errors.
    phase2Errors: _verdict.effectiveErrors,
    phase2ChunkErrors: result.errors.length,
    ...persistenceFields('phase2Persons', _verdict),
    phase2CompletedAt: new Date().toISOString(),
  });

  // A phase that submitted work and landed nothing is a failed phase, not a
  // completed one. Refusing here is the difference between a counter and a gate.
  if (_verdict.status === STATUS.NO_ROWS_LANDED) {
    throw new Error(
      `Phase 2 wrote nothing: ${_verdict.submitted} person(s) submitted, store holds 0. ${_verdict.reasons.join('; ')}`,
    );
  }
}

// ---------------------------------------------------------------------------
// Phase 3: Classify + AI draft via TriageOrchestrator
// Uses StaticEmailAdapter (reads from gmail-index-30d.json) to avoid
// needing a fresh Gmail token when the index already exists.
// ---------------------------------------------------------------------------
async function phase3RunTriage(opts: {
  account: ReturnType<typeof getAccount>;
  since: Date;
  until: Date;
  limit: number;
  dryRun: boolean;
  offline: boolean;
  skipDrafts?: boolean;
  resetPhase3?: boolean;
}): Promise<TriageItem[]> {
  const { account, since, until, limit, dryRun, offline } = opts;
   console.log(`\nPhase 3/4: Running triage (29-signal classify + AI draft)...`);
   sendIPC({ type: 'phase', ts: Date.now(), phase: '3', label: 'Triage', state: 'running' });
   console.log(`  Since: ${since.toISOString()}`);
   console.log(`  Limit: ${limit}`);
   console.log(`  Chunk size: ${PHASE3_CHUNK_SIZE} emails/batch`);
   console.log(`  Inter-batch delay: ${PHASE3_INTER_BATCH_DELAY_MS}ms`);

   // Start health monitor - auto-shrinks chunk size at >6.5 GiB, pauses Qwen3 at >8 GiB
   //
   // BACKFILL-GRAPH-SWEEP-1: gated on the legacy opt-in. Despite the
   // memory-pressure framing, lib/broker/health-monitor.js polls GRAPH -
   // _pollStorage and _pollTransactions each issue a rawRead on a timer. A
   // driver-creation trace identified this as the first graph query on a
   // --dry-run --offline run, and once one driver exists graph-transport's own
   // pool health check and reconnect loop keep connecting for the rest of the
   // process. With no graph engine there is no storage or transaction state to
   // poll, so every tick was a pure connection attempt.
   if (legacyGraphEnabled()) _startBackfillHealthMonitor();

  // Raise storage access timeout for Phase 3's batch writes.
  // Default is 1s (--storage-access-timeout-sec=1). ensureStorageTimeout() in
  // graph-transport.js sets it to 25s lazily on first use, but under pool pressure
  // (session leaks, concurrent GC) even 25s can be insufficient for 200-email batches.
  // Set to 60s here explicitly before Phase 3 begins.
  // Source: graph.com/docs/help-center/errors/transactions#storage-access-timeout
  //   "Cannot get shared access to the storage" â€” fix: SET DATABASE SETTING 'storage.access_timeout_sec' TO '60'
  //   Valid range: [1, 1000000]. Not persistent between restarts.
  if (!dryRun) {
    try {
      const mgP3 = (() => { try { return require('./lib/graph/graph-transport.js'); } catch { return null; } })() as any;
      if (mgP3?.rawWrite) await mgP3.rawWrite("SET DATABASE SETTING 'storage.access_timeout_sec' TO '60'");
    } catch { /* non-fatal */ }
  }

  if (dryRun) {
    console.log('  [dry-run] skipping triage');
    return [];
  }

  // â”€â”€ Choose message source â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // ensureTokenFresh() refreshes in-process if expired â€” no manual pre-run needed
  const tokenPath = resolveTokenPath(account!.tokenPath);
  const tokenFresh = !offline && await ensureTokenFresh(tokenPath);

  // During a backfill, always prefer the static local index over the live API.
  // The local index is what Phase 2 ingested into Graph â€” triage must operate
  // on the same message set. Using the live API here would:
  //   1. Re-fetch 10k+ messages, blowing the Gmail quota instantly
  //   2. Only see the last ~200 messages (live adapter default page size)
  //   3. Miss the 90-day window already captured in the local index
  // Only fall through to live adapter when no local index exists at all.
  const indexPath = existsSync(INDEX_30D_PATH) ? INDEX_30D_PATH
    : existsSync(EXISTING_INDEX_PATH) ? EXISTING_INDEX_PATH
    : null;

  const useStaticAdapter = indexPath !== null;

  // For live adapter (no local index): delegate to a single orchestrator.run().
  // For static adapter (local index exists): pre-load and chunk to avoid pool exhaustion.
  if (tokenFresh && !offline && !useStaticAdapter) {
    console.log('  Using live Gmail adapter (token is fresh, no local index) â€” single-pass mode...');
    const adapter = new LiveGmailAdapter(account!, until);
    return _phase3SinglePass({ adapter, since, limit, tokenFresh: true, opts });
  }

  if (!indexPath) {
    console.error('  âœ— No message source available. Run Phase 1 first.');
    return [];
  }

  console.log(`  Using static adapter â€” chunked mode (source: ${indexPath})`);

  // Load and filter the full message list once up-front
  const fullAdapter = new StaticGmailAdapter(indexPath, since, until, limit);
  const allMessages = await fullAdapter.fetch();
  console.log(`  Total messages after date filter: ${allMessages.length}`);

  if (allMessages.length === 0) {
    console.log('  No messages in window â€” skipping triage.');
    return [];
  }

  // OBS3: Enrichment pre-flight check (runs once before chunking)
  // Uses rawRead (direct Bolt) not safeRead (broker) to avoid timeout behind Phase 2 write backlog
  // Sample nodes that SHOULD have these properties â€” nodes with KNOWS edges for clustering,
  // and nodes with FAVEE snapshots for trajectoryVelocity. Using LIMIT 10 on all Person nodes
  // returns the first 10 by internal ID which may be isolated nodes that T1-D never touches.
  try {
    const { rawRead: _pfRead } = require('./lib/graph/graph-transport.js');
    const samplePersons = await _pfRead(
      `MATCH (p:Person)
       WHERE (p)-[:KNOWS]-() OR p.clusteringCoefficient IS NOT NULL
       RETURN p.trajectoryVelocity, p.clusteringCoefficient, p.avgMessageLength
       LIMIT 10`,
      {}
    );
    const hasTrajectory = samplePersons.some((r: any) => r['p.trajectoryVelocity'] != null);
    const hasCluster = samplePersons.some((r: any) => r['p.clusteringCoefficient'] != null);
    const hasStyle = samplePersons.some((r: any) => r['p.avgMessageLength'] != null);
    if (!hasTrajectory) console.warn('[ENRICHMENT GAP] trajectoryVelocity is null for all sampled contacts â€” run warm-tick to populate');
    if (!hasCluster) console.warn('[ENRICHMENT GAP] clusteringCoefficient is null for all sampled contacts â€” run warm-tick to populate');
    if (!hasStyle) console.warn('[ENRICHMENT GAP] avgMessageLength is null for all sampled contacts â€” run warm-tick to populate');
    try {
      const knowsRows = await _pfRead('MATCH ()-[k:KNOWS]->() WHERE k.qualityProfile IS NOT NULL RETURN count(k) AS cnt LIMIT 1', {});
      if (!knowsRows[0] || knowsRows[0].cnt === 0) console.warn('[ENRICHMENT GAP] k.qualityProfile is null on all KNOWS edges â€” run warm-tick to populate');
    } catch { /* non-blocking */ }
  } catch { /* non-blocking */ }

  // â”€â”€ Chunk-based Phase 3 with checkpoint resume â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Load Phase 3 chunk checkpoint (separate from the main pipeline checkpoint)
  if (opts.resetPhase3 && existsSync(PHASE3_CHECKPOINT_PATH)) {
    require('node:fs').rmSync(PHASE3_CHECKPOINT_PATH);
    console.log('  [--phase3-reset] Cleared Phase 3 chunk checkpoint â€” restarting from offset 0');
  }

  const phase3Ckpt = existsSync(PHASE3_CHECKPOINT_PATH)
    ? JSON.parse(readFileSync(PHASE3_CHECKPOINT_PATH, 'utf-8'))
    : null;
  let startOffset: number = phase3Ckpt?.offset ?? 0;

  if (startOffset > 0 && startOffset < allMessages.length) {
    console.log(`  Resuming Phase 3 from offset ${startOffset}/${allMessages.length} (${allMessages.length - startOffset} remaining)`);
  }

  const allItems: TriageItem[] = [];
  const statsAccum = { p0Count: 0, p1Count: 0, p2Count: 0, p3Count: 0, draftCount: 0 };

  // SIGTERM / SIGINT handler: flush the current offset to the checkpoint before
  // the OS kills the process. Without this, a mid-batch Windows OOM kill (which
  // sends SIGTERM to Node.js) leaves the checkpoint at the last successfully
  // completed batch â€” or at the start if no batch finished yet â€” causing the
  // next run to replay already-processed batches or skip ahead.
  // We track the in-progress offset in a mutable object so the handler can read
  // the latest value even mid-await inside orchestrator.run().
  const _p3State = { currentOffset: startOffset, inProgress: true };
  const _p3SigtermHandler = () => {
    if (_p3State.inProgress && _p3State.currentOffset > 0) {
      try {
        writeFileSync(PHASE3_CHECKPOINT_PATH, JSON.stringify({
          offset: _p3State.currentOffset,
          killedAt: new Date().toISOString(),
          note: 'process killed mid-batch â€” resume from this offset',
        }));
        process.stderr.write(`\n[phase3] SIGTERM received â€” checkpoint flushed at offset ${_p3State.currentOffset}\n`);
      } catch { /* best-effort */ }
    }
  };
  process.once('SIGTERM', _p3SigtermHandler);
  process.once('SIGINT',  _p3SigtermHandler);
  // NOTE: process.on('SIGTERM') does NOT fire on Windows â€” OOM kills are hard terminations.
  // The primary resilience mechanism is periodic checkpoint writes every PERIODIC_CKPT_INTERVAL
  // batches below. SIGTERM handler is secondary for Linux/macOS graceful shutdowns only.
  const PERIODIC_CKPT_INTERVAL = 5; // write checkpoint every 5 batches regardless of signal

  for (let offset = startOffset; offset < allMessages.length; offset += PHASE3_CHUNK_SIZE) {
    _p3State.currentOffset = offset;
    const chunk = allMessages.slice(offset, offset + PHASE3_CHUNK_SIZE);
    const batchNum = Math.floor(offset / PHASE3_CHUNK_SIZE) + 1;
    const totalBatches = Math.ceil(allMessages.length / PHASE3_CHUNK_SIZE);

    // Periodic checkpoint write: write current offset BEFORE processing the batch.
    // This is the primary resilience mechanism on Windows where SIGTERM is not catchable.
    // If the process is killed mid-batch, next run resumes from this offset (re-processes
    // the in-progress batch once â€” idempotent via Graph rawId dedup).
    if (batchNum % PERIODIC_CKPT_INTERVAL === 1 || batchNum === 1) {
      try {
        writeFileSync(PHASE3_CHECKPOINT_PATH, JSON.stringify({
          offset,
          periodicAt: new Date().toISOString(),
          note: 'pre-batch checkpoint â€” safe to resume from here',
        }));
      } catch { /* best-effort â€” don't block batch processing */ }
    }

    console.log(`\n  [Phase 3 batch ${batchNum}/${totalBatches}] Processing ${chunk.length} messages (offset ${offset}â€“${offset + chunk.length - 1})...`);

    const chunkAdapter = StaticGmailAdapter.fromMessages(chunk);
    const orchestrator = new TriageOrchestrator({
      ...TRIAGE_BACKFILL_PRESET,
      limitPerChannel: chunk.length,
      channels: [chunkAdapter],
      skipDrafts: opts.skipDrafts ?? false,
      persistBodies: true,
      log: (msg: string) => process.stderr.write(`[triage:b${batchNum}] ${msg}\n`),
    });

    const result = await orchestrator.run({
      since,
      limit: chunk.length,
      backfill: true,
      skipDedup: true, // static adapter is already date-filtered; dedup via Graph rawId is skipped for speed
    });

    if (!result.success) {
      const errMsg = result.error ?? '';
      // If Graph dropped mid-batch, wait for recovery and retry once
      const isGraphDown = errMsg.includes('ECONNREFUSED') ||
        errMsg.includes('Graph unavailable') ||
        errMsg.includes('connection refused') ||
        errMsg.includes('Failed to connect');
      if (isGraphDown) {
        const recovered = await waitForGraph(120_000, `batch ${batchNum}`);
        if (recovered) {
          console.log(`  â†© Retrying batch ${batchNum} after Graph recovery...`);
          // Retry the same batch once
          const retryOrchestrator = new TriageOrchestrator({
            ...TRIAGE_BACKFILL_PRESET,
            limitPerChannel: chunk.length,
            channels: [StaticGmailAdapter.fromMessages(chunk)],
            skipDrafts: opts.skipDrafts ?? false,
            persistBodies: true,
            log: (msg: string) => process.stderr.write(`[triage:b${batchNum}:retry] ${msg}\n`),
          });
          const retryResult = await retryOrchestrator.run({ since, limit: chunk.length, backfill: true, skipDedup: true });
          if (retryResult.success) {
            const batchItems2 = retryResult.items ?? [];
            allItems.push(...batchItems2);
            statsAccum.p0Count += retryResult.stats?.p0Count ?? 0;
            statsAccum.p1Count += retryResult.stats?.p1Count ?? 0;
            statsAccum.p2Count += retryResult.stats?.p2Count ?? 0;
            statsAccum.p3Count += retryResult.stats?.p3Count ?? 0;
            // continue to next batch
          } else {
            console.error(`  âœ— Batch ${batchNum} retry also failed: ${retryResult.error}`);
            writeFileSync(PHASE3_CHECKPOINT_PATH, JSON.stringify({ offset, failedAt: new Date().toISOString() }));
            break;
          }
        } else {
          console.error(`  âœ— Graph did not recover â€” stopping Phase 3 at offset ${offset}`);
          writeFileSync(PHASE3_CHECKPOINT_PATH, JSON.stringify({ offset, failedAt: new Date().toISOString() }));
          break;
        }
      } else {
        console.error(`  âœ— Batch ${batchNum}/${totalBatches} failed at offset ${offset}: ${errMsg}`);
        console.error(`  Stopping Phase 3 â€” checkpoint saved at offset ${offset}. Re-run to resume.`);
        writeFileSync(PHASE3_CHECKPOINT_PATH, JSON.stringify({ offset, failedAt: new Date().toISOString() }));
        break;
      }
    }

    // Accumulate results
    const batchItems = result.items ?? [];
    allItems.push(...batchItems);
    statsAccum.p0Count += result.stats?.p0Count ?? 0;
    statsAccum.p1Count += result.stats?.p1Count ?? 0;
    statsAccum.p2Count += result.stats?.p2Count ?? 0;
    statsAccum.p3Count += result.stats?.p3Count ?? 0;
    statsAccum.draftCount += batchItems.filter(i => i.autoDraft).length;

    console.log(`  âœ“ Batch ${batchNum}/${totalBatches}: P0=${result.stats.p0Count} P1=${result.stats.p1Count} P2=${result.stats.p2Count} P3=${result.stats.p3Count} drafts=${batchItems.filter(i => i.autoDraft).length}`);

    // Save chunk checkpoint after each successful batch
    const nextOffset = offset + PHASE3_CHUNK_SIZE;
    writeFileSync(PHASE3_CHECKPOINT_PATH, JSON.stringify({
      offset: nextOffset,
      completedBatches: batchNum,
      totalMessages: allMessages.length,
      updatedAt: new Date().toISOString(),
    }));

    // REFINE-6: record monotonic chunk checkpoint into durable receipt store
    try {
      const receiptJobId = process.env.ELYNTIC_BACKFILL_RECEIPT_JOB_ID || 'gmail-backfill-active';
      const { GmailBackfillReceiptStore } = require('./daemon/lib/gmail-backfill-receipt-store.js');
      const receiptStore = new GmailBackfillReceiptStore();
      receiptStore.recordChunkCheckpoint({
        jobId: receiptJobId,
        chunkIndex: batchNum,
        offset: nextOffset,
        chunkSize: chunk.length,
        messagesProcessed: Math.min(nextOffset, allMessages.length),
        persistenceStatus: 'persisted',
      });
      receiptStore.close();
    } catch {
      // Non-fatal receipt store chunk checkpoint
    }

    // F5: inter-batch delay â€” gives Graph GC time between bulk writes
    if (nextOffset < allMessages.length && PHASE3_INTER_BATCH_DELAY_MS > 0) {
      process.stderr.write(`[triage] inter-batch delay ${PHASE3_INTER_BATCH_DELAY_MS}ms...\n`);
      await new Promise(r => setTimeout(r, PHASE3_INTER_BATCH_DELAY_MS));
    }
  }

  // Phase 3 loop finished â€” deregister signal handlers, mark state done
  _p3State.inProgress = false;
  process.off('SIGTERM', _p3SigtermHandler);
  process.off('SIGINT',  _p3SigtermHandler);

  // â”€â”€ Aggregate stats and write drafts â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
   console.log(`\n  âœ“ Phase 3 complete (all batches):`);
   sendIPC({ type: 'phase', ts: Date.now(), phase: '3', label: 'Triage', state: 'done' });
   sendIPC({ type: 'metric', ts: Date.now(), key: 'p0', value: statsAccum.p0Count });
   sendIPC({ type: 'metric', ts: Date.now(), key: 'p1', value: statsAccum.p1Count });
   sendIPC({ type: 'metric', ts: Date.now(), key: 'p2', value: statsAccum.p2Count });
   sendIPC({ type: 'metric', ts: Date.now(), key: 'p3', value: statsAccum.p3Count });
   sendIPC({ type: 'metric', ts: Date.now(), key: 'drafts', value: statsAccum.draftCount });
  console.log(`    P0 (action required): ${statsAccum.p0Count}`);
  console.log(`    P1 (review):          ${statsAccum.p1Count}`);
  console.log(`    P2 (FYI):             ${statsAccum.p2Count}`);
  console.log(`    P3 (archive):         ${statsAccum.p3Count}`);
  console.log(`    Total items:          ${allItems.length}`);

  await _phase3WriteDrafts(allItems);

  saveCheckpoint(CHECKPOINT_PATH, {
    lastKey: 'phase3_complete',
    phase3P0: statsAccum.p0Count,
    phase3P1: statsAccum.p1Count,
    phase3P2: statsAccum.p2Count,
    phase3P3: statsAccum.p3Count,
    phase3DraftCount: statsAccum.draftCount,
    phase3TotalItems: allItems.length,
    phase3CompletedAt: new Date().toISOString(),
  });

  return allItems;
}

// ---------------------------------------------------------------------------
// phase3SinglePass â€” live adapter path (token fresh); original single-run behaviour
// ---------------------------------------------------------------------------
async function _phase3SinglePass(opts: {
  adapter: ChannelAdapter;
  since: Date;
  limit: number;
  tokenFresh: boolean;
  opts: Parameters<typeof phase3RunTriage>[0];
}): Promise<TriageItem[]> {
  const { adapter, since, limit } = opts;
  const outerOpts = opts.opts;

  const orchestrator = new TriageOrchestrator({
    ...TRIAGE_BACKFILL_PRESET,
    limitPerChannel: limit,
    channels: [adapter],
    skipDrafts: outerOpts.skipDrafts ?? false,
    persistBodies: true,
    log: (msg: string) => process.stderr.write(`[triage] ${msg}\n`),
  });

  console.log('  Running TriageOrchestrator.run() with backfill=true...');
  const result = await orchestrator.run({ since, limit, backfill: true, skipDedup: false });

  if (!result.success) {
    console.error(`  âœ— Triage failed: ${result.error}`);
    return [];
  }

  const stats = result.stats;
  console.log(`  âœ“ Triage complete: P0=${stats.p0Count} P1=${stats.p1Count} P2=${stats.p2Count} P3=${stats.p3Count}`);

  if (result.timings) {
    const t = result.timings;
    console.log(`  Timings: fetch=${t.fetch ?? 0}ms extract=${t.extract ?? 0}ms classify=${t.classify ?? 0}ms draft=${t.autoDraft ?? 0}ms total=${t.total ?? 0}ms`);
  }

  const items = result.items ?? [];
  await _phase3WriteDrafts(items);

  saveCheckpoint(CHECKPOINT_PATH, {
    lastKey: 'phase3_complete',
    phase3P0: stats.p0Count,
    phase3P1: stats.p1Count,
    phase3P2: stats.p2Count,
    phase3P3: stats.p3Count,
    phase3DraftCount: items.filter(i => i.autoDraft).length,
    phase3TotalItems: items.length,
    phase3CompletedAt: new Date().toISOString(),
  });

  return items;
}

// ---------------------------------------------------------------------------
// _phase3WriteDrafts â€” write drafted-responses.json from TriageItem results
// ---------------------------------------------------------------------------
async function _phase3WriteDrafts(items: TriageItem[]): Promise<void> {
  const draftItems = items.filter(i => i.autoDraft && (i.priority === 'P0' || i.priority === 'P1'));
  console.log(`  Auto-drafts generated: ${draftItems.length}`);

  mkdirSync(TRIAGE_DIR, { recursive: true });
  const draftsPath = join(TRIAGE_DIR, 'drafted-responses.json');

  if (draftItems.length === 0) {
    if (existsSync(draftsPath)) {
      try {
        const existing = JSON.parse(readFileSync(draftsPath, 'utf-8'));
        const hasPlaceholders = Array.isArray(existing) && existing.some((d: any) => d.body === 'Hello send');
        if (hasPlaceholders) {
          writeFileSync(draftsPath, JSON.stringify([], null, 2));
          console.log('  Cleared old placeholder test drafts from drafted-responses.json');
        }
      } catch { /* ignore parse errors */ }
    }
    return;
  }

  const drafts = await Promise.all(draftItems.map(async item => {
    const isLenderLegal = isLenderOrLegalEmail(item);
    if (isLenderLegal) {
      const _domain = (item.senderHandle ?? '').split('@').pop()?.toLowerCase() ?? '';
      const _enrichment = _domain ? await fetchLegalEnrichment(item.senderName, _domain) : null;
      const fwd = buildAttorneyForwardDraft({ ...item }, _enrichment);
      // Preserve fwd- prefix for downstream blocked-draft detection;
      // tag with backfill marker for idempotency dedup.
      return { ...fwd, id: `${fwd.id}-backfill`, backfill: true };
    }
    return {
      id: `backfill-${item.id}`,
      action: 'reply',
      target_id: item.id,
      channel: item.platform || 'email',
      to: item.senderHandle,
      subject: item.subject,
      body: item.autoDraft!,
      drafted_at: new Date().toISOString(),
      priority: item.priority,
      senderName: item.senderName,
      model: (item as any).autoDraftModelId || process.env.ELYNTIC_MODEL_ID || process.env.ELYNTIC_PROVIDER || 'unknown',
      personModel: item.autoDraftModel || null,
      backfill: true,
      draft_failed: (item as any).draft_failed || undefined,
    };
  }));

  // Merge with existing drafts file (append-safe â€” avoids overwriting drafts from previous batches)
  let existing: any[] = [];
  try {
    // Use try/catch directly â€” avoids TOCTOU race between existsSync and readFileSync
    const raw = readFileSync(draftsPath, 'utf-8');
    const parsed = JSON.parse(raw);
    existing = Array.isArray(parsed) ? parsed : [];
  } catch { existing = []; }
  const existingIds = new Set(existing.map((d: any) => d.id));
  const newDrafts = drafts.filter(d => !existingIds.has(d.id));
  const merged = [...existing, ...newDrafts];
  writeFileSync(draftsPath, JSON.stringify(merged, null, 2));

  const forwardCount = drafts.filter((d: any) => d.action === 'forward').length;
  const replyCount = drafts.filter((d: any) => d.action === 'reply').length;
  console.log(`  âœ“ Wrote ${merged.length} total drafts (${newDrafts.length} new) â†’ ${draftsPath}`);
  console.log(`    ${forwardCount} FORWARD to attorney â€” lender/legal`);
  console.log(`    ${replyCount} REPLY drafts â€” standard`);

  const sample = drafts[0];
  if (sample) {
    console.log(`\n  Sample draft [${sample.priority}] action=${sample.action}:`);
    console.log(`    To: ${sample.to}`);
    console.log(`    Subject: ${(sample.subject || '').substring(0, 70)}`);
    console.log(`    Body preview: ${(sample.body || '').substring(0, 120)}...`);
  }
}

// ---------------------------------------------------------------------------
// Phase 3b: Persist email bodies back to Graph
// Phase 2 ingests full messages (body + headers). Phase 3 also fetches live full bodies.
// This phase writes those bodies back to the Email nodes created in Phase 2.
// ---------------------------------------------------------------------------
// DEPRECATED: phase3bPersistBodies() is now handled by TriageOrchestrator
// when persistBodies: true is set in the orchestrator config.
// Kept as no-op for backward compatibility.
async function phase3bPersistBodies(_items: TriageItem[]): Promise<void> {
  console.log('\nPhase 3b: Body persistence now handled by TriageOrchestrator (persistBodies: true)');
}

// ---------------------------------------------------------------------------
// Phase 4: Generate/refresh HTML dashboard
// ---------------------------------------------------------------------------
async function phase4GenerateDashboard(dryRun: boolean): Promise<void> {
  console.log(`\nPhase 4/4: Generating dashboard...`);
  sendIPC({ type: 'phase', ts: Date.now(), phase: '4', label: 'Dashboard', state: 'running' });

  // Skip internal regen if invoked via HTTP route (daemon already regens on process close)
  if (process.env.ELYNTIC_SKIP_INTERNAL_DASHBOARD_REGEN === '1') {
    console.log('\nPhase 4/4: Dashboard regen skipped (daemon route handles post-completion regen)');
    return;
  }

  if (dryRun) {
    console.log('  [dry-run] skipping dashboard generation');
    return;
  }

  try {
    const outputPath = await generateDashboard();
    console.log(`  âœ“ Dashboard generated â†’ ${outputPath}`);
  } catch (err: any) {
    // Non-fatal: dashboard requires ~/.pi/triage/dashboard-template.html
    console.log(`  Dashboard: ${err.message?.includes('template') ? 'template not found â€” skipping' : err.message}`);
  }

  saveCheckpoint(CHECKPOINT_PATH, {
    lastKey: 'phase4_complete',
    phase4CompletedAt: new Date().toISOString(),
  });
}

// ---------------------------------------------------------------------------
// Main entrypoint
// ---------------------------------------------------------------------------

/**
 * Probe the graph engine through the transport — returns true when a query round-trips.
 */
async function probeGraph(timeoutMs = 3000): Promise<boolean> {
  // Query-level probe through the graph transport (lib/graph/graph-transport.js): owner
  // mode in the daemon, the daemon-hosted broker everywhere else. Bounded so a
  // store that is still opening costs the probe budget, not a driver default.
  try {
    const mg = require('./lib/graph/graph-transport.js');
    const probe = await Promise.race([
      mg.probeConnectionStrict(timeoutMs),
      new Promise<{ graphReady: boolean }>((resolve) => setTimeout(() => resolve({ graphReady: false }), timeoutMs + 500)),
    ]);
    return !!probe?.graphReady;
  } catch {
    return false;
  }
}

/**
 * Wait for Graph to become reachable, optionally restarting it via WSL.
 * Called when Graph drops mid-backfill (e.g. WSL crash, memory pressure, OOM).
 * Returns true if Graph came back, false if it didn't within the timeout.
 *
 * Why this matters: Graph can restart automatically via elyntic-boot.sh / supervisord.
 * Rather than aborting the backfill, we wait for it to recover and continue.
 * Worst case: ~2 min wait during Graph snapshot recovery (330MB+ graph).
 */
async function waitForGraph(timeoutMs = 120_000, label = ''): Promise<boolean> {
  const tag = label ? `[${label}] ` : '';
  const deadline = Date.now() + timeoutMs;
  process.stdout.write(`  ${tag}Graph store unavailable — waiting for the daemon broker`);
  while (Date.now() < deadline) {
    await new Promise(r => setTimeout(r, 3000));
    if (await probeGraph(2000)) {
      console.log(` recovered after ${Math.round((Date.now() - (deadline - timeoutMs)) / 1000)}s`);
      return true;
    }
    process.stdout.write('.');
  }
  console.log(' timed out');
  return false;
}

/**
 * Make sure the graph store answers before the graph phases start.
 *
 * The graph is the LadybugDB store owned by the Elyntic daemon; this worker
 * reaches it through the daemon-hosted broker via lib/graph/graph-transport.js. There is
 * nothing to launch from here — if the daemon is not up yet we wait for its
 * broker with the same budget the old WSL/Docker start path used.
 *
 * Returns a cleanup function for signature compatibility (always a no-op).
 */
async function ensureGraphDb(): Promise<() => void> {
  if (await probeGraph()) {
    console.log('  Graph DB: LadybugDB store reachable through the daemon broker');
    return () => {};
  }
  process.stdout.write('  Graph DB: not yet reachable — waiting for the daemon broker');
  const deadline = Date.now() + 95_000;
  while (Date.now() < deadline) {
    if (await probeGraph(1000)) {
      console.log(' ready.');
      return () => {};
    }
    process.stdout.write('.');
    await new Promise(r => setTimeout(r, 2000));
  }
  console.error('\n✗ Graph store not reachable after 95s.');
  console.error('  Start the Elyntic daemon: it owns the LadybugDB store and hosts the graph broker this worker uses.');
  process.exit(1);
}

// ============================================================================
// Phase 5: Organization mapping
// Transplanted from scripts/run-backfill.ts (lines 659â€“1007).
// Variable name adaptations:
//   SELF_ID  â†’ opts.selfId   (passed from main() via process.env.ELYNTIC_SELF_ID)
//   skipLLM  â†’ opts.skipLLM  (driven by --skip-enrichment flag in run-backfill-30d.ts)
//   argv     â†’ opts.dryRun   (parsed in parseArgs())
// ============================================================================

const B2C_DOMAINS_P5 = new Set([
  'chase.com','jpmorganchase.com','bankofamerica.com','wellsfargo.com','citi.com',
  'americanexpress.com','amex.com','capitalone.com','discover.com','usaa.com',
  'ally.com','sofi.com','affirm.com','klarna.com','afterpay.com','paypal.com',
  'venmo.com','cash.app','squareup.com','robinhood.com','coinbase.com','lendio.com',
  'lendingclub.com','sezzle.com','splitwise.com','amazon.com','ebay.com','etsy.com',
  'overstock.com','target.com','walmart.com','netflix.com','hulu.com','spotify.com',
  'soundcloud.com','primevideo.com','facebook.com','facebookmail.com','instagram.com',
  'twitter.com','x.com','linkedin.com','google.com','youtube.com','reddit.com',
  'quora.com','slack.com','goodreads.com','openai.com','anthropic.com','hilton.com',
  'marriott.com','hyatt.com','delta.com','grubhub.com','doordash.com','draftkings.com',
  'usps.com','fedex.com','ups.com','steampowered.com',
]);

const NOTIFICATION_DOMAINS_P5 = new Set([
  'github.com','noreply.github.com','notifications.github.com','gitlab.com',
  'bitbucket.org','atlassian.net','beehiiv.com','substack.com','mailchimp.com',
  'sendgrid.net','mailgun.org','nextdoor.com',
]);

const ROLE_PREFIXES_P5 = [
  'noreply','no-reply','donotreply','do-not-reply','notifications','notification',
  'alerts','alert','newsletter','newsletters','marketing','billing','invoice',
  'statement','receipts','payments','account','accounts','service','services',
  'support','info','hello','team','contact','welcome','mailer','mail','bounce',
  'bounces','postmaster','abuse','admin','webmaster','security','privacy',
  'automated','system','robot','bot','daemon','reply','no_reply','no.reply',
];

const PERSONAL_DOMAINS_P5 = new Set([
  'gmail.com','yahoo.com','yahoo.co.uk','hotmail.com','outlook.com','icloud.com',
  'me.com','mac.com','protonmail.com','proton.me','aol.com','live.com','msn.com',
]);

const CANONICAL_NAMES_P5: Record<string, string> = {
  'github':'GitHub','google':'Google','amazon':'Amazon','microsoft':'Microsoft',
  'apple':'Apple','meta':'Meta','linkedin':'LinkedIn','netflix':'Netflix',
  'paypal':'PayPal','stripe':'Stripe','openai':'OpenAI','anthropic':'Anthropic',
  'jpmorgan':'J.P. Morgan','jpmorganchase':'JPMorgan Chase',
  'americanexpress':'American Express','hbr':'Harvard Business Review',
  'usps':'USPS','amazonaws':'Amazon Web Services','soundcloud':'SoundCloud',
};

const ORG_PROMPT_P5 = `Extract formal organizational affiliations from these facts about a person.

STRICT RULES:
- "employment": person works AT that employer ("works at Acme", "CEO of Stripe")
- "member": formal membership in trade association, consortium, board, political party
- "founder": created or co-founded the organization
- "board": sits on board of directors
- "investor": has invested money
- "alumni": past member/student/employee
- "partner": formal commercial partnership agreement
- "contractor": non-employee contractor

DO NOT extract:
- Service subscriptions (Adobe, Hulu, AWS) as "member" â€” those are vendor relationships
- Technology integrations (uses Stripe API) as any membership type
- Newsletter subscriptions as memberships
- B2C brands a person uses as their employer (unless explicitly stated)

For each qualifying affiliation output:
{"groupName":"name","groupType":"company|educational|association|government|family|social_group|community|other","membershipType":"employment|board|advisor|investor|founder|alumni|member|partner|contractor","title":null,"isCurrent":true,"confidence":0.6-1.0}

Return [] if no qualifying affiliations. Output ONLY a valid JSON array.`;

function classifyDomainP5(name: string | null, email: string | null, selfDomainsSet: Set<string>): {
  cls: 'human_b2b'|'human_b2c'|'brand_sender'|'notification'|'role_based'|'newsletter'|'github_bot'|'skip';
  domain: string | null;
  orgName: string | null;
} {
  const n = (name ?? '').trim();
  const e = (email ?? '').toLowerCase();
  const dm = e.match(/@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/);
  const raw = dm?.[1] ?? null;
  const subdomainPrefixes = /^(mail|smtp|email|bounce|send|notifications|m|e)\./i;
  let domain: string | null = raw;
  while (domain && subdomainPrefixes.test(domain)) {
    domain = domain.replace(subdomainPrefixes, '');
  }
  const lp = e.split('@')[0] ?? '';
  if (!domain) return { cls: 'skip', domain: null, orgName: null };
  // selfDomainsSet is pre-computed once by the caller â€” never re-allocated per call
  if (selfDomainsSet.has(domain) || PERSONAL_DOMAINS_P5.has(domain)) return { cls: 'skip', domain, orgName: null };

  const base = domain.split('.').slice(-2)[0] ?? '';
  const orgName = CANONICAL_NAMES_P5[base.toLowerCase()] ?? (base.charAt(0).toUpperCase() + base.slice(1));

  if (domain === 'github.com' || /^[a-z0-9_-]+\/[a-z0-9_.-]+$/i.test(n)) {
    return { cls: 'github_bot', domain: 'github.com', orgName: 'GitHub' };
  }
  const isNotification = [...NOTIFICATION_DOMAINS_P5].some(nd => domain === nd || domain!.endsWith('.' + nd));
  if (isNotification) return { cls: 'notification', domain, orgName };
  const lpClean = lp.replace(/[._+-]/g, '');
  if (ROLE_PREFIXES_P5.some(p => lpClean === p || lpClean.startsWith(p))) return { cls: 'role_based', domain, orgName };

  const nn = n.toLowerCase().replace(/[^a-z0-9]/g, '');
  const no = orgName.toLowerCase().replace(/[^a-z0-9]/g, '');
  if (nn && no && (nn === no || nn.includes(no) || no.includes(nn))) return { cls: 'brand_sender', domain, orgName };

  if (/[A-Z]{5,}/.test(n) || n.includes(' â€” ') || n.includes(' | ') ||
      /\b(Daily|Weekly|Newsletter|Digest|Brief|Bulletin|Roundup)\b/i.test(n) ||
      (/\b(Stop|Fight|Save|Protect|Action|Campaign|Fund|Senate|Congress|Vote)\b/i.test(n) && n.split(' ').length > 2)) {
    return { cls: 'newsletter', domain, orgName };
  }

  const isHuman = n.length >= 4 && !/[/_\d@#]/.test(n) && !/^[A-Z\s]+$/.test(n) &&
                  !n.includes(' â€” ') && n.split(/\s+/).length <= 5 &&
                  n.replace(/[^a-zA-Z]/g, '').length >= 4;

  if (B2C_DOMAINS_P5.has(domain)) return { cls: isHuman ? 'human_b2c' : 'brand_sender', domain, orgName };
  return { cls: isHuman ? 'human_b2b' : 'brand_sender', domain, orgName };
}

function normalizeOrgP5(name: string): string {
  return name.toLowerCase().replace(/\s+(inc\.?|llc\.?|ltd\.?|corp\.?|co\.?)$/i, '').replace(/[^a-z0-9\s]/g, '').trim();
}

function toIntP5(v: any): number {
  if (v == null) return 0;
  if (typeof v === 'number') return v;
  if (typeof v === 'bigint') return Number(v);
  // Check .toNumber() BEFORE .low: legacy Integer wrappers have both,
  // but .low is only the lower 32 bits and silently truncates counts >= 2^31.
  // .toNumber() returns the correct full 64-bit value as a JS float.
  if (typeof v?.toNumber === 'function') return v.toNumber();
  if (v?.low !== undefined) return v.low;
  return Number(v) || 0;
}

async function phase5OrgMapping(opts: {
  selfId: string;
  skipLLM: boolean;
  dryRun: boolean;
  limit: number;
}): Promise<void> {
  const { selfId, skipLLM, dryRun, limit } = opts;
  // Use _require (module-level createRequire) to be explicit â€” avoids tsx polyfill dependency
  const _mg = (() => {
    try { return _require('./lib/graph/graph-transport.js') as any; } catch { return null; }
  })();
  if (!_mg) { console.log('\nPhase 5/5: Org mapping â€” skipped (graph-transport unavailable)'); return; }
  const { rawRead: p5Read, rawWrite: p5Write } = _mg;

  // Hoist selfDomains: computed ONCE here at function scope so it's available in
  // both the banner log and Step B's classify loop â€” never re-allocated per-person.
  // Derived through resolveSelfEmailDomains (extensions/email/auth/accounts.ts): the
  // SELF_EMAIL_DOMAINS override, the owner's mailbox, and every enabled configured
  // account. Nothing to derive from is a NAMED refusal, never a built-in domain list.
  let p5SelfDomains = new Set<string>();
  let p5DomainsUnresolved: string | null = null;
  try {
    p5SelfDomains = new Set(resolveSelfEmailDomains({
      override: process.env.SELF_EMAIL_DOMAINS,
      selfEmail: process.env.ELYNTIC_SELF_EMAIL || opts.selfId || null,
    }));
  } catch (error) {
    p5DomainsUnresolved = (error as any)?.code ?? (error as Error).message;
  }

  // Banner: show effective config so operators can verify the right account is running
  const _p5selfIdDisplay = selfId || '(empty â€” ELYNTIC_SELF_ID not set)';
  const _p5domainDisplay = [...p5SelfDomains].join(', ') || `(${p5DomainsUnresolved}: set SELF_EMAIL_DOMAINS or ELYNTIC_SELF_EMAIL, or enable an account)`;
  console.log(`\nPhase 5/5: Organization mapping...`);
  sendIPC({ type: 'phase', ts: Date.now(), phase: '5', label: 'Org mapping', state: 'running' });
  console.log(`  selfId:      ${_p5selfIdDisplay}`);
  console.log(`  selfDomains: ${_p5domainDisplay}`);
  console.log(`  skipLLM:     ${skipLLM}`);
  console.log(`  dryRun:      ${dryRun}`);

  // Step A: clean previous bad mappings
  try {
    const willDelete = await p5Read(
      `MATCH (p:Person)-[:MEMBER_OF]->(m:Membership {source:'email_domain'})-[:IN_GROUP]->(g:Group)
       WHERE toLower(replace(p.name,' ','')) = toLower(replace(g.name,' ',''))
          OR g.domain IN $b2c
       RETURN count(m) AS cnt`,
      { b2c: [...B2C_DOMAINS_P5] }
    );
    console.log(`  Step A: will delete ${toIntP5(willDelete?.[0]?.cnt)} bad email-domain memberships`);
    if (!dryRun) {
      await p5Write(
        `MATCH (p:Person)-[:MEMBER_OF]->(m:Membership {source:'email_domain'})-[:IN_GROUP]->(g:Group)
         WHERE toLower(replace(p.name,' ','')) = toLower(replace(g.name,' ',''))
            OR g.domain IN $b2c
         DETACH DELETE m`,
        { b2c: [...B2C_DOMAINS_P5] }
      );
      await p5Write(
        `MATCH (p:Person)-[:MEMBER_OF]->(m:Membership {source:'email_domain'})
         WHERE p.name CONTAINS '/' OR p.name IN ['Assign','Author','Push','Review requested','Ci activity']
            OR p.name CONTAINS 'BREAKING' OR p.name CONTAINS ' â€” '
         DETACH DELETE m`
      );
      await p5Write(`MATCH (g:Group) WHERE NOT ()-[:IN_GROUP]->(g) DETACH DELETE g`);
    }
  } catch (e: any) {
    console.warn(`  âš  Step A (non-fatal): ${e?.message?.slice(0, 80)}`);
  }

  // Step B: domain-based org nodes + B2B employment edges
  // Uses UNWIND batching (500/batch) instead of per-person queries â€” prevents
  // 10,000+ sequential Graph round-trips that would take 10+ minutes and
  // exhaust the connection pool (adversarial review finding #3).
  try {
    // Guard: if selfId is empty, the filter `p.id <> ''` matches everyone including self.
    // Skip Step B entirely when selfId is unset to avoid self-org-tagging.
    if (!selfId) {
      console.log('  Step B: skipped â€” ELYNTIC_SELF_ID not set (cannot distinguish self from contacts)');
    } else if (p5DomainsUnresolved) {
      // Same reason as the selfId guard above: without the owner's own domains every
      // colleague on the owner's domain would be org-tagged as an outside company.
      console.warn(`  Step B: refused - ${p5DomainsUnresolved} (cannot tell the owner's own domains from contacts)`);
    } else {
    const persons = await p5Read(
      `MATCH (p:Person) WHERE p.email IS NOT NULL AND p.id IS NOT NULL AND p.id <> $selfId
       RETURN p.id AS pid, p.name AS pname, p.email AS email`,
      { selfId }
    );
    // p5SelfDomains is hoisted to function scope above â€” used here and in the banner log
    const stats = { groups: 0, employment: 0 };

    // Pre-classify all persons in JS â€” O(N) with no I/O
    const groupBatch: Array<{ id: string; name: string; norm: string; domain: string }> = [];
    const employmentBatch: Array<{ pid: string; gid: string; mid: string }> = [];
    const githubBatch: Array<{ pid: string }> = [];
    const dryRunCounts = { groups: 0, employment: 0 };

    for (const row of persons) {
      const { cls, domain, orgName } = classifyDomainP5(row.pname as string, row.email as string, p5SelfDomains);
      if (!domain || !orgName || cls === 'skip' || cls === 'newsletter') continue;
      const gid = `group-domain-${domain.replace(/\./g, '-')}`;
      const norm = normalizeOrgP5(orgName);
      groupBatch.push({ id: gid, name: orgName, norm, domain });
      dryRunCounts.groups++;
      if (cls === 'github_bot') {
        githubBatch.push({ pid: String(row.pid) });
      } else if (cls === 'human_b2b') {
        employmentBatch.push({ pid: String(row.pid), gid, mid: `membership-domain-${row.pid}-${gid}` });
        dryRunCounts.employment++;
      }
    }

    if (dryRun) {
      console.log(`  Step B (dry-run): would create ~${dryRunCounts.groups} org nodes, ~${dryRunCounts.employment} employment edges`);
    } else {
      const CHUNK = 500;
      // Deduplicate groups before writing (multiple persons may share the same domain)
      const uniqueGroups = [...new Map(groupBatch.map(g => [g.id, g])).values()];

      // Write Group nodes in batches
      for (let i = 0; i < uniqueGroups.length; i += CHUNK) {
        const chunk = uniqueGroups.slice(i, i + CHUNK);
        try {
          await p5Write(
            `UNWIND $batch AS g
             MERGE (grp:Group {id: g.id})
             ON CREATE SET grp.name=g.name, grp.normalizedName=g.norm, grp.type='company',
               grp.domain=g.domain, grp.isActive=true, grp.source='email_domain', grp.confidence=0.7,
               grp.createdAt=localdatetime(), grp.updatedAt=localdatetime()
             ON MATCH SET grp.updatedAt=localdatetime()`,
            { batch: chunk }
          );
          stats.groups += chunk.length;
        } catch (e: any) { console.warn(`  âš  Step B group chunk ${i}: ${e?.message?.slice(0, 60)}`); }
      }

      // Write employment Membership edges in batches
      for (let i = 0; i < employmentBatch.length; i += CHUNK) {
        const chunk = employmentBatch.slice(i, i + CHUNK);
        try {
          await p5Write(
            `UNWIND $batch AS row
             MATCH (p:Person {id: row.pid}), (g:Group {id: row.gid})
             MERGE (p)-[:MEMBER_OF]->(m:Membership {id: row.mid})
             ON CREATE SET m.type='employment', m.isCurrent=true, m.isPrimary=false,
               m.source='email_domain', m.confidence=0.65,
               m.createdAt=localdatetime(), m.updatedAt=localdatetime()
             MERGE (m)-[:IN_GROUP]->(g)`,
            { batch: chunk }
          );
          stats.employment += chunk.length;
        } catch (e: any) { console.warn(`  âš  Step B employment chunk ${i}: ${e?.message?.slice(0, 60)}`); }
      }

      // Tag GitHub bot senders in batches
      for (let i = 0; i < githubBatch.length; i += CHUNK) {
        const chunk = githubBatch.slice(i, i + CHUNK);
        try {
          await p5Write(
            `UNWIND $batch AS row MATCH (p:Person {id: row.pid}) SET p.senderType='github_notification'`,
            { batch: chunk }
          );
        } catch { /* non-fatal */ }
      }

      console.log(`  âœ“ Step B: ${stats.groups} org nodes, ${stats.employment} employment edges`);
    }
    } // end selfId guard
  } catch (e: any) {
    console.warn(`  âš  Step B (non-fatal): ${e?.message?.slice(0, 80)}`);
  }

  // Step C: KeyFact LLM extraction — local Qwen via qwen-llm.ts (was the last
  // remaining direct Bedrock call in the backfill path; silently skipped whenever
  // AWS_BEARER_TOKEN_BEDROCK was unset, so org enrichment never ran).
  if (!skipLLM && !dryRun) {
    {
      try {
        const { callQwen } = await import('./lib/triage-core/mental-model/qwen-llm.ts');
        const kfPersons = await p5Read(
          `MATCH (me:Person {id: $selfId})-[:KNOWS]->(p:Person)-[:HAS_FACT]->(kf:KeyFact)
           WHERE p.id IS NOT NULL
           WITH p, collect(kf.text) AS facts
           RETURN p.id AS pid, p.name AS pname, facts
           LIMIT toInteger($limit)`,
          { selfId, limit }
        );
        let kfMemberships = 0;
        for (let i = 0; i < kfPersons.length; i++) {
          const row = kfPersons[i];
          if (i % 25 === 0 && i > 0) console.log(`  Step C: ${i}/${kfPersons.length} persons...`);
          const facts = ((row.facts as string[]) ?? []).filter((f: string) => f?.length > 10).slice(0, 20);
          if (!facts.length) continue;
          try {
            const text = await callQwen(
              ORG_PROMPT_P5,
              `Facts about ${row.pname}:\n- ${facts.join('\n- ')}`,
              { maxTokens: 1024 }
            );
            const match = text.match(/\[[\s\S]*\]/);
            if (!match) continue;
            let affs: any[];
            try { affs = JSON.parse(match[0]); } catch { continue; }
            for (const aff of affs) {
              if (!aff.groupName || (aff.confidence ?? 0) < 0.6) continue;
              const norm = normalizeOrgP5(aff.groupName);
              const pnorm = normalizeOrgP5(String(row.pname ?? ''));
              if (norm === pnorm || (norm.length > 3 && pnorm.includes(norm))) continue;
              const gtype = aff.groupType ?? 'company';
              const gid = `group-${gtype}-${norm.replace(/\s+/g, '-').slice(0, 40)}`;
              const mid = `membership-kf-${row.pid}-${gid}`;
              await p5Write(
                `MERGE (g:Group {id: $gid})
                 ON CREATE SET g.name=$name, g.normalizedName=$norm, g.type=$type, g.isActive=true,
                   g.source='keyfact_llm', g.confidence=$conf,
                   g.createdAt=localdatetime(), g.updatedAt=localdatetime()
                 ON MATCH SET g.name=CASE WHEN $conf>g.confidence THEN $name ELSE g.name END,
                   g.updatedAt=localdatetime()`,
                { gid, name: aff.groupName, norm, type: gtype, conf: aff.confidence }
              );
              await p5Write(
                `MATCH (p:Person {id: $pid}), (g:Group {id: $gid})
                 MERGE (p)-[:MEMBER_OF]->(m:Membership {id: $mid})
                 ON CREATE SET m.type=$mtype, m.title=$title, m.isCurrent=$cur, m.isPrimary=false,
                   m.source='keyfact_llm', m.confidence=$conf,
                   m.createdAt=localdatetime(), m.updatedAt=localdatetime()
                 ON MATCH SET m.title=CASE WHEN $conf>m.confidence AND $title IS NOT NULL THEN $title ELSE m.title END,
                   m.updatedAt=localdatetime()
                 MERGE (m)-[:IN_GROUP]->(g)`,
                { pid: row.pid, gid, mid, mtype: aff.membershipType ?? 'employment',
                  title: aff.title ?? null, cur: aff.isCurrent ?? true, conf: aff.confidence }
              );
              kfMemberships++;
            }
          } catch { /* non-fatal per-person error */ }
          await new Promise(r => setTimeout(r, 400));
        }
        console.log(`  âœ“ Step C: ${kfMemberships} memberships from ${kfPersons.length} persons`);
      } catch (e: any) {
        console.warn(`  âš  Step C (non-fatal): ${e?.message?.slice(0, 80)}`);
      }
    }
  } else if (skipLLM) {
    console.log('  Step C: Org LLM extraction â€” skipped (--skip-enrichment)');
  }

  // Step D: set isPrimary on dominant employment â€” single atomic transaction.
  // Previously two separate p5Write calls: if the process died between them, all
  // Memberships in the KNOWS graph had isPrimary=false permanently (DATA_LOSS).
  // Fix: chain reset + set in one Cypher query using WITH so it runs in one transaction.
  if (!dryRun && selfId) {
    try {
      await p5Write(
        `MATCH (:Person {id: $selfId})-[:KNOWS]->(p:Person)-[:MEMBER_OF]->(m:Membership)-[:IN_GROUP]->(:Group)
         SET m.isPrimary = false
         WITH p
         MATCH (p)-[:MEMBER_OF]->(mw:Membership)-[:IN_GROUP]->(:Group)
         WHERE mw.type IN ['employment','founder'] AND mw.isCurrent = true
         WITH p, mw ORDER BY mw.confidence DESC, mw.startDate DESC
         WITH p, collect(mw)[0] AS winner
         WHERE winner IS NOT NULL
         SET winner.isPrimary = true`,
        { selfId }
      );
      const gs = await p5Read('MATCH (g:Group) RETURN count(g) AS cnt', {});
      const ms = await p5Read('MATCH (m:Membership) RETURN count(m) AS cnt', {});
      const ps = await p5Read('MATCH (p:Person)-[:MEMBER_OF]->(:Membership)-[:IN_GROUP]->(:Group) RETURN count(DISTINCT p) AS cnt', {});
      console.log(`  âœ“ Phase 5 complete: ${toIntP5(gs[0]?.cnt)} groups, ${toIntP5(ms[0]?.cnt)} memberships, ${toIntP5(ps[0]?.cnt)} persons enriched`);
      sendIPC({ type: 'phase', ts: Date.now(), phase: '5', label: 'Org mapping', state: 'done',
        groups: toIntP5(gs[0]?.cnt), memberships: toIntP5(ms[0]?.cnt), persons: toIntP5(ps[0]?.cnt) });
    } catch (e: any) {
      console.warn(`  âš  Step D (non-fatal): ${e?.message?.slice(0, 80)}`);
    }
  } else if (!selfId) {
    console.log('  Step D: skipped â€” ELYNTIC_SELF_ID not set');
  }
}

function emitCoordinatorEvent(event: Record<string, unknown>): void {
  process.stdout.write(`ELYNTIC_BACKFILL_EVENT ${JSON.stringify(event)}\n`);
}

let _coordinatedProgressSequence = 0;
type CoordinatorProgressInput = {
  stageKey: string;
  stageLabel: string;
  completed: number;
  total?: number;
  knownTotal: boolean;
  active: number;
  failed: number;
  startedAt: string;
  progressAt: string;
  elapsedMs: number;
};

function emitCoordinatorProgress(progress: CoordinatorProgressInput): void {
  if (!COORDINATED) return;
  emitCoordinatorEvent({
    ...progress,
    type: 'progress',
    version: 1,
    attempt: Number(process.env.ELYNTIC_BACKFILL_ATTEMPT || 0),
    phase: COORDINATOR_PHASE,
    seq: ++_coordinatedProgressSequence,
  });
}

function coordinatedIdentity(): { companyId: string; providerAccountId: string; spoolRoot: string } {
  const companyId = process.env.ELYNTIC_BACKFILL_COMPANY_ID || '';
  const providerAccountId = process.env.ELYNTIC_BACKFILL_PROVIDER_ACCOUNT_ID || '';
  const spoolRoot = process.env.ELYNTIC_EMAIL_INGEST_SPOOL || '';
  if (!companyId || !providerAccountId || !spoolRoot) {
    throw new Error('coordinated worker requires company, provider account, and spool identity');
  }
  return { companyId, providerAccountId, spoolRoot };
}

function bindCoordinatedSelfIdentity(accountEmail: string): string {
  const normalizedEmail = parseEmailAddress(accountEmail).email;
  if (!normalizedEmail) {
    throw new Error('coordinated worker requires a valid authenticated account email');
  }
  process.env.ELYNTIC_SELF_EMAIL = normalizedEmail;
  if (!process.env.ELYNTIC_SELF_ID) {
    process.env.ELYNTIC_SELF_ID = `person:email:${normalizedEmail}`;
  }
  return normalizedEmail;
}

function emailCacheAccountId(account: { email?: string } | null | undefined): string {
  if (COORDINATED_FETCH) return coordinatedIdentity().providerAccountId;
  return account?.email?.split('@')[0] ?? 'unknown';
}

function coordinatedProvenance(): {
  backfillRunId: string;
  capturedAt: string;
  cutoffAt: string;
  windowEndAt: string;
} {
  return coordinatedWindow(process.env);
}

function admittedBackfillMessages(
  messages: unknown,
  since: Date,
  until: Date,
  source: string,
): any[] {
  return admitPinnedBackfillMessages(
    messages,
    { cutoffAt: since, windowEndAt: until },
    source,
  );
}

function verifyCanonicalAcknowledgements(): void {
  if (!COORDINATED_ENRICH) return;
  const index = process.argv.indexOf('--canonical-acked-batches');
  const batchIds = index >= 0
    ? String(process.argv[index + 1] || '').split(',').filter(Boolean)
    : [];
  if (batchIds.length === 0) throw new Error('enrichment requires canonical ACK batch identities');
  const identity = coordinatedIdentity();
  for (const batchId of batchIds) {
    if (!isBatchAcknowledged({ ...identity, batchId })) {
      throw new Error(`canonical ACK missing for ${batchId}`);
    }
  }
}

function coordinatedBatchIdsFromArgs(): string[] {
  const index = process.argv.indexOf('--canonical-acked-batches');
  return index >= 0
    ? String(process.argv[index + 1] || '').split(',').filter(Boolean)
    : [];
}

function verifyGraphProjectionReceipts(): {
  projectionEpoch: number;
  projectionGenerationPath: string;
  projectionGenerationSha256: string;
} | null {
  if (!COORDINATED_ENRICH) return null;
  const epochIndex = process.argv.indexOf('--projection-epoch');
  const projectionEpoch = epochIndex >= 0 ? Number(process.argv[epochIndex + 1]) : NaN;
  if (!Number.isSafeInteger(projectionEpoch) || projectionEpoch < 1) {
    throw new Error('enrichment requires a current graph projection epoch');
  }
  const identity = coordinatedIdentity();
  const manifest = readGraphProjectionRunManifest({
    ...identity,
    backfillRunId: process.env.ELYNTIC_BACKFILL_JOB_ID,
    batchIds: coordinatedBatchIdsFromArgs(),
  });
  const expectedPath = process.env.ELYNTIC_BACKFILL_PROJECTION_GENERATION_PATH || '';
  const expectedSha256 = process.env.ELYNTIC_BACKFILL_PROJECTION_GENERATION_SHA256 || '';
  if (!manifest
    || manifest.projectionEpoch !== projectionEpoch
    || manifest.currentGenerationPath !== expectedPath
    || manifest.currentGenerationSha256 !== expectedSha256) {
    throw new Error('enrichment projection generation changed after coordinator admission');
  }
  return {
    projectionEpoch,
    projectionGenerationPath: expectedPath,
    projectionGenerationSha256: expectedSha256,
  };
}

async function runCoordinatedCanonicalEnrichment(
  projection: NonNullable<ReturnType<typeof verifyGraphProjectionReceipts>>,
  skipDrafts: boolean,
): Promise<void> {
  const identity = coordinatedIdentity();
  const window = coordinatedProvenance();
  const batchIds = coordinatedBatchIdsFromArgs();
  const batches = batchIds.map(batchId => assertBatchForRun({
    ...identity,
    batchId,
    backfillRunId: window.backfillRunId,
    cutoffAt: window.cutoffAt,
    windowEndAt: window.windowEndAt,
  }));
  const binding = {
    companyId: identity.companyId,
    providerAccountId: identity.providerAccountId,
    backfillRunId: window.backfillRunId,
    projectionEpoch: projection.projectionEpoch,
  };
  const messages = canonicalBatchRecordsToRawMessages(batches, binding);
  const graphRecords = messages.map(message => ({ providerObjectId: message.providerObjectId! }));
  const { rawRead } = require('./lib/graph/graph-transport.js') as {
    rawRead: (query: string, params?: Record<string, unknown>) => Promise<Record<string, unknown>[]>;
  };
  await assertCanonicalGraphProjectionReady(graphRecords, binding, rawRead);
  const adapter = StaticGmailAdapter.fromMessages(messages);
  const accountRoot = process.env.ELYNTIC_BACKFILL_ACCOUNT_DATA_DIR || '';
  if (!accountRoot) throw new Error('coordinated enrichment requires an authenticated account root');
  const orchestrator = new TriageOrchestrator({
    ...TRIAGE_BACKFILL_PRESET,
    channels: [adapter],
    cacheDir: join(accountRoot, 'runtime', 'email-triage'),
    skipDrafts,
    suppressBackgroundQueues: true,
    canonicalProjection: binding,
    log: line => process.stderr.write(`${line}\n`),
    onProgress: progress => emitCoordinatorProgress(progress),
  });
  const result = await orchestrator.run({
    since: new Date(window.cutoffAt),
    limit: messages.length,
    backfill: true,
    skipDedup: true,
  });
  if (!result.success) throw new Error(result.message || 'canonical projection triage failed');
  await assertCanonicalGraphProjectionReady(graphRecords, binding, rawRead);
  _forensicWrite({
    event: 'canonical_projection_enrichment_complete',
    status: 'ok',
    records: messages.length,
    projectionEpoch: projection.projectionEpoch,
  });
  emitCoordinatorEvent({
    type: 'enrichment_complete',
    projectionEpoch: projection.projectionEpoch,
    projectionGenerationPath: projection.projectionGenerationPath,
    projectionGenerationSha256: projection.projectionGenerationSha256,
    records: messages.length,
  });
  sendIPC({ type: 'pipeline_complete', ts: Date.now() });
}

function materializeCoordinatedEmailAttachments(messages: any[]): any[] {
  if (!COORDINATED_FETCH) return messages;
  const identity = coordinatedIdentity();
  const accountDataDir = process.env.ELYNTIC_BACKFILL_ACCOUNT_DATA_DIR || '';
  if (!accountDataDir) throw new Error('coordinated worker attachment account root is required');
  const canonicalStorageRoot = join(accountDataDir, 'attachments');
  const storageRoot = process.env.ELYNTIC_EMAIL_ATTACHMENT_STORE || canonicalStorageRoot;
  if (resolve(storageRoot) !== resolve(canonicalStorageRoot)) {
    throw new Error('coordinated worker attachment store must remain inside its authenticated account root');
  }
  return messages.map((message: any) => {
    const result = materializeAvailableInboundAttachments({
      storageRoot,
      providerAccountId: identity.providerAccountId,
      providerObjectId: message.providerObjectId ?? message.messageId ?? message.id,
      providerThreadId: message.threadId ?? message.providerThreadId ?? message.messageId ?? message.id,
      attachments: message.attachments,
    });
    const retainedOmissions = Array.isArray(message.attachmentOmissions)
      ? message.attachmentOmissions
      : [];
    return {
      ...message,
      attachments: result.attachments,
      ...((retainedOmissions.length > 0 || result.omissions.length > 0)
        ? { attachmentOmissions: [...retainedOmissions, ...result.omissions] }
        : {}),
    };
  });
}
function stageCanonicalEmailBatches(): void {
  if (!COORDINATED_FETCH) return;
  if (!existsSync(INDEX_30D_PATH)) {
    throw new Error(`Gmail index missing after fetch: ${INDEX_30D_PATH}`);
  }
  const identity = coordinatedIdentity();
  const provenance = coordinatedProvenance();
  const sourceMessages = readEmailIndexFile(INDEX_30D_PATH);
  const admittedMessages = admittedBackfillMessages(
    sourceMessages,
    new Date(provenance.cutoffAt),
    new Date(provenance.windowEndAt),
    'canonical spool index',
  );
  const stagingStartedAt = new Date().toISOString();
  const stagingStartedMs = Date.parse(stagingStartedAt);
  emitCoordinatorProgress({
    stageKey: 'stage_canonical_batches',
    stageLabel: 'Stage canonical batches',
    completed: 0,
    knownTotal: false,
    active: 1,
    failed: 0,
    startedAt: stagingStartedAt,
    progressAt: stagingStartedAt,
    elapsedMs: 0,
  });
  const messages = materializeCoordinatedEmailAttachments(admittedMessages);
  // Persist only stored manifests; retries re-verify existing bytes through the
  // same materializer and never retain provider payload bytes in the index.
  writeJsonArrayFile(INDEX_30D_PATH, messages);
  const checkpoint = loadCheckpoint(CHECKPOINT_PATH);
  const cursorBefore = readCommittedCursor(identity);
  const cursorAfter = typeof checkpoint?.lastHistoryId === 'string'
    ? checkpoint.lastHistoryId
    : cursorBefore;
  const batches = stageEmailIngestBatches({
    ...identity,
    messages,
    cursorBefore,
    cursorAfter,
    maxRecords: Number(process.env.ELYNTIC_EMAIL_INGEST_BATCH_SIZE || 250),
    ...provenance,
    onProgress: ({ completedRecords, totalRecords }: {
      completedRecords: number;
      totalRecords: number;
    }) => {
      const progressAt = new Date().toISOString();
      emitCoordinatorProgress({
        stageKey: 'stage_canonical_batches',
        stageLabel: 'Stage canonical batches',
        completed: completedRecords,
        total: totalRecords,
        knownTotal: true,
        active: completedRecords < totalRecords ? 1 : 0,
        failed: 0,
        startedAt: stagingStartedAt,
        progressAt,
        elapsedMs: Math.max(0, Date.parse(progressAt) - stagingStartedMs),
      });
    },
  });
  emitCoordinatorEvent({
    type: 'canonical_batches_pending',
    batchIds: batches.map((batch: any) => batch.batchId),
    cursorBefore,
    cursorAfter,
    records: messages.length,
  });
}

export async function runBackfillWorker(): Promise<void> {
  // Signal all MAGE maintenance jobs (betweenness, node2vec) to skip their
  // full-graph scans while backfill is running. Those scans hold exclusive locks
  // that deadlock with concurrent backfill writes and GC transactions.
  process.env.ELYNTIC_BACKFILL_MODE = '1';

  const parsedOptions = parseArgs();
  const { account: accountId, since, until, limit, dryRun, reset, resetPhase3, offline, skipDrafts, skipEnrichment, enrichmentOnly, skipChannels, skipOrg, maxCost, force } = parsedOptions;

  assertCoordinatedEnrichmentOnly({
    coordinated: COORDINATED,
    coordinatorPhase: COORDINATOR_PHASE,
    enrichmentOnly,
    skipEnrichment,
  });

  // This check deliberately precedes graph startup. The internal consumer may
  // not touch graph enrichment until Elyntic has ACKed every canonical batch.
  verifyCanonicalAcknowledgements();
  assertBackfillGraphPolicy({
    coordinated: COORDINATED,
    coordinatorPhase: COORDINATOR_PHASE,
    skipGraph: process.env.ELYNTIC_SKIP_GRAPH,
  });
  const projection = verifyGraphProjectionReceipts();
  const workerStartedAt = new Date().toISOString();
  emitCoordinatorProgress({
    stageKey: 'worker_start',
    stageLabel: 'Start coordinated worker',
    completed: 0,
    total: 1,
    knownTotal: true,
    active: 1,
    failed: 0,
    startedAt: workerStartedAt,
    progressAt: workerStartedAt,
    elapsedMs: 0,
  });

  console.log('â•”â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•—');
  console.log('â•‘  Elyntic Email Backfill Pipeline                         â•‘');
  console.log('â•šâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•');

  // â”€â”€ Ensure graph DB is up before doing anything else â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // On Windows: auto-starts bundled Bolt if not already running.
  // On macOS/Linux: requires user-managed Graph (exits with clear error if down).
  // In production (helios-desktop app): LocalBoltService handles this â€” backfill
  // is called after the service confirms bolt is ready, so this probe will pass instantly.
  // BACKFILL-GRAPH-SWEEP-1: gated on the legacy opt-in.
  // ensureGraphDb is the Graph LIFECYCLE MANAGER, not a consumer: it probes
  // bolt, and when the probe fails it tries to START a server (bundled binary,
  // start-graph.sh, WSL systemctl) and then polls bolt until it answers.
  // Measured with a listener bound to the sentinel port, this single call
  // produced the overwhelming majority of 99 observed bolt connections on a
  // --dry-run --offline run that touched no graph data at all.
  if (!COORDINATED_FETCH && legacyGraphEnabled()) {
    console.log('\nChecking graph database...');
    await ensureGraphDb();
  }


  if (COORDINATED_ENRICH) {
    if (!projection) throw new Error('coordinated enrichment requires a bound projection generation');
    await runCoordinatedCanonicalEnrichment(projection, skipDrafts);
    return;
  }

  console.log(`\nConfig:`);
  console.log(`  account=${accountId}`);
  console.log(`  since=${since.toISOString()}`);
  console.log(`  until=${until.toISOString()}`);
  console.log(`  limit=${limit}`);
  console.log(`  dryRun=${dryRun}`);
  console.log(`  offline=${offline}`);
  if (skipEnrichment) console.log(`  mode=fast (--skip-enrichment: Phase 2.5 skipped)`);
  if (enrichmentOnly) console.log(`  mode=enrichment-only (Phases 1+2+3 skipped)`);
  if (process.env.BACKFILL_SAMPLE_LIMIT) console.log(`  mode=canary (--sample ${process.env.BACKFILL_SAMPLE_LIMIT})`);
  if (process.argv.includes('--stress')) console.log('  mode=stress (semaphore=4)');
  if (process.env.BACKFILL_SAMPLE_LIMIT || process.argv.includes('--stress')) {
    // RSS slope over the canary window stands in for long-horizon leak checks.
    const _rssTimer = setInterval(() => _forensicWrite({ event: 'rss', rss: process.memoryUsage().rss }), 60_000);
    (_rssTimer as any).unref?.();
  }

  // --reset: clear Phase 2.5 and Phase 3 checkpoints only â€” never Phase 1.
  // Phase 1 (Gmail fetch) is always protected; use --force-phase1 to re-fetch.
  // Phases 2/2.5/3 always re-run by default so config changes are always picked up.
  if (reset) {
    // Only clear the phase 2.5 step checkpoint (not the main checkpoint which guards Phase 1)
    const phase25Path = join(DATA_DIR, 'phase25-checkpoint.json');
    if (existsSync(phase25Path)) {
      require('node:fs').rmSync(phase25Path);
      console.log('  â†º Phase 2.5 checkpoint cleared');
    }
    if (existsSync(PHASE3_CHECKPOINT_PATH)) {
      require('node:fs').rmSync(PHASE3_CHECKPOINT_PATH);
      console.log('  â†º Phase 3 checkpoint cleared (--reset)');
    }
  }

  // Resolve account config
  // If the specified account ID is not found, fall back to the first enabled Gmail account.
  // WARN explicitly â€” silent fallback previously caused a personal-domain account â†’ work-domain account
  // substitution with no indication in the log that the wrong account was used.
  const _requestedAccount = getAccount(accountId)
    ?? getEnabledAccounts('gmail').find(candidate => candidate.email === accountId);
  // Coordinated launches carry an exact provider-account identity. Falling back
  // would turn a missing config entry into a cross-account data leak.
  const account = _requestedAccount ?? (COORDINATED ? undefined : getEnabledAccounts('gmail')[0]);
  if (!account) {
    console.error(`âœ— No account found for id="${accountId}".`);
    console.error(`  Check ~/.pi/outreach/gmail-accounts/accounts.json`);
    process.exit(1);
  }
  const selfEmail = COORDINATED
    ? bindCoordinatedSelfIdentity(account.email)
    : process.env.ELYNTIC_SELF_EMAIL;
  if (!_requestedAccount && account) {
    console.warn(`\nâš  Account "${accountId}" not found â€” falling back to first enabled account: ${account.email}`);
    console.warn(`  To use a specific account, ensure it is registered in accounts.json`);
  }

  // Check token freshness â€” refresh in-process if expired
  const tokenPath = resolveTokenPath(account.tokenPath);
  const tokenFresh = !offline && await ensureTokenFresh(tokenPath);
  console.log(`\nAccount: ${account.email} (${account.provider})`);
  console.log(`Token: ${tokenFresh ? 'FRESH â€” will use live Gmail API' : 'EXPIRED/MISSING â€” will use existing gmail-index.json'}`);

  // Load checkpoint
  const checkpoint = loadCheckpoint(CHECKPOINT_PATH);
  const completedPhases = new Set<string>(
    checkpoint
      ? Object.keys(checkpoint).filter(k => k.startsWith('phase') && k.endsWith('CompletedAt'))
      : []
  );
  console.log(`Checkpoint: ${completedPhases.size > 0 ? [...completedPhases].join(', ') : 'none (fresh start)'}`);

  // WS3: abort before any phase on silent-zero misconfigurations
  if (!COORDINATED_FETCH) await runPreflight({
    force: process.argv.includes('--force'),
    selfEmail,
  });

  // â”€â”€ Phases 1â€“3: Skipped when --enrichment-only is set â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // --enrichment-only runs Phase 2.5 only â€” no sync, no ingest, no triage.
  // This is the nightly batch path (scheduled at 2am).
  if (!enrichmentOnly) { // Phases 1 + 2
  if (!COORDINATED_ENRICH) { // Phase 1 source sync

  // â”€â”€ Phase 1: Incremental sync on every run â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // On EVERY run: check for new emails via historyId delta sync (State B).
  // This ensures new emails arriving within the 90-day window are always picked up
  // without re-fetching the full 10k+ message corpus.
  //
  // States:
  //   State A â€” no local index              â†’ full fetch
  //   State B â€” local index + historyId     â†’ delta sync (history.list) â€” pulls only new
  //   State C â€” local index, no historyId   â†’ getProfile to get historyId, save for next run
  //             If coverage < 80%           â†’ full fetch to fill gaps
  //
  // historyId is stored in a dedicated lightweight file (phase1-history.json) that
  // persists across runs and is never cleared unless --force-phase1 is passed.
  // This file is separate from the main checkpoint so --reset never affects Phase 1.
  //
  // Source: developers.google.com/workspace/gmail/api/guides/sync

  const HISTORY_ID_PATH = join(ELYNTIC_DATA_DIR, 'phase1-history.json');
  const forcePhase1 = process.argv.includes('--force-phase1');

  // Load persisted historyId (independent of main checkpoint)
  let storedHistoryId: string | undefined;
  if (!forcePhase1 && COORDINATED_FETCH) {
    storedHistoryId = readCommittedCursor(coordinatedIdentity()) ?? undefined;
  } else if (!forcePhase1 && existsSync(HISTORY_ID_PATH)) {
    try {
      const h = JSON.parse(readFileSync(HISTORY_ID_PATH, 'utf-8'));
      storedHistoryId = h.historyId ?? undefined;
    } catch { /* corrupt file â€” ignore */ }
  }

  let phase1ShouldFetch = true;

  if (!forcePhase1 && existsSync(INDEX_30D_PATH)) {
    try {
      const existing = [...iterateJsonArrayFile(INDEX_30D_PATH)];
      const sinceMs = since.getTime();
      const untilMs = until.getTime();
      const inWindow = existing.filter((m: any) => {
        if (!m.date) return false;
        const d = new Date(m.date);
        return !isNaN(d.getTime()) && d.getTime() >= sinceMs && d.getTime() <= untilMs;
      });

      const coordinatedIndexNeedsAttachmentRefetch = COORDINATED_FETCH && inWindow.some((message: any) =>
        Array.isArray(message.attachments) && message.attachments.some((attachment: any) =>
          !Object.prototype.hasOwnProperty.call(attachment ?? {}, 'dataBase64')
          && !isStoredAttachment(attachment)
        )
      );

      if (inWindow.length === 0) {
        console.log('\n  Local index exists but no messages in window â€” will full sync');
      } else if (coordinatedIndexNeedsAttachmentRefetch) {
        console.log('\n  Local index has attachment metadata without retained bytes — will full sync');
      } else if (!offline && await ensureTokenFresh(resolveTokenPath(account!.tokenPath))) {
        const { GmailProvider } = await import('./extensions/email/providers/gmail.ts');
        const provider = new GmailProvider({ account: account! });
        // This legacy delta path needs Gmail operations that the provider does
        // not yet expose publicly. Keep the runtime access in one typed seam.
        const gmail = (provider as unknown as { gmail: any }).gmail;

        // â”€â”€ State B: delta sync via history.list (always attempted when historyId available) â”€â”€
        // Pulls ONLY messages added since last sync â€” fast, quota-efficient, runs every time.
        if (storedHistoryId) {
          try {
            const histRes = await gmail.users.history.list({
              userId: 'me',
              startHistoryId: storedHistoryId,
              historyTypes: ['messageAdded'],
              labelId: 'INBOX',
            });
            const newMessages = histRes.data.history?.flatMap((h: any) => h.messagesAdded || []) || [];
            const newHistoryId = histRes.data.historyId;

            console.log(`\nPhase 1/4: Delta sync â€” ${newMessages.length} new messages since last sync (historyId: ${storedHistoryId})`);

            if (newMessages.length === 0) {
              console.log('  Index is up to date. No new messages.');
              phase1ShouldFetch = false;
            } else {
              console.log(`  Fetching ${newMessages.length} new messages (batches of 50)...`);
              const newFull: any[] = [];
              const BATCH_SIZE = 50;
              for (let bi = 0; bi < newMessages.length; bi += BATCH_SIZE) {
                const batchItems = newMessages.slice(bi, bi + BATCH_SIZE);
                const batchResults = await Promise.allSettled(
                  batchItems.map((item: any) =>
                    gmail.users.messages.get({
                      userId: 'me', id: item.message.id, format: 'full',
                      fields: 'id,threadId,labelIds,snippet,internalDate,payload(headers,body,parts)',
                    })
                  )
                );
                for (let j = 0; j < batchResults.length; j++) {
                  const r = batchResults[j];
                  if (r.status !== 'fulfilled') throw r.reason;
                   const detail = r.value;
                  try {
                    const headers = detail.data.payload?.headers || [];
                    const h = (name: string) => headers.find((x: any) => x.name?.toLowerCase() === name)?.value || '';
                    // Extract full body from payload â€” same logic as fetchAllInbox extractBody()
                    const extractBody = (payload: any): string => {
                      if (!payload) return '';
                      const parts = payload.parts || [];
                      let body = ''; let htmlBody = '';
                      const find = (ps: any[]): void => {
                        for (const part of ps) {
                          if (part.mimeType === 'text/plain' && part.body?.data) { body = Buffer.from(part.body.data, 'base64').toString('utf-8'); return; }
                          if (part.mimeType === 'text/html' && part.body?.data && !htmlBody) htmlBody = Buffer.from(part.body.data, 'base64').toString('utf-8');
                          if (part.parts) find(part.parts);
                        }
                      };
                      find(parts);
                      if (!body && payload.body?.data) body = Buffer.from(payload.body.data, 'base64').toString('utf-8');
                      if (!body && htmlBody) body = htmlBody.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
                      return body;
                    };
                    newFull.push({
                      messageId: batchItems[j].message.id,
                      threadId: detail.data.threadId || '',
                      from: h('from'), to: splitAddressList(h('to')),
                      cc: splitAddressList(h('cc')),
                      subject: h('subject'),
                      date: h('date') || new Date(parseInt(detail.data.internalDate || '0', 10)).toISOString(),
                      body: extractBody(detail.data.payload),
                      snippet: detail.data.snippet || '', labels: detail.data.labelIds || [],
                    });
                  } catch (err) { throw err; }
                }
                if (bi + BATCH_SIZE < newMessages.length) {
                  await new Promise(resolve => setTimeout(resolve, 200));
                }
              }
              // Merge new messages into existing index
              const existingIds = new Set(existing.map((m: any) => m.messageId));
              const merged = [...existing, ...newFull.filter((m: any) => !existingIds.has(m.messageId))];
              upsertEmailCacheBatch(merged, emailCacheAccountId(account), since.toISOString());
              mkdirSync(DATA_DIR, { recursive: true });
              writeJsonArrayFile(INDEX_30D_PATH, merged);
              console.log(`  âœ“ Index updated: ${existing.length} + ${newFull.length} = ${merged.length} total`);
              phase1ShouldFetch = false;
            }

            // Always persist the new historyId for the next run
            if (newHistoryId) {
              if (newMessages.length === 0) {
                upsertEmailCacheBatch(existing, emailCacheAccountId(account), since.toISOString());
              }
              if (!COORDINATED_FETCH) {
                writeFileSync(HISTORY_ID_PATH, JSON.stringify({ historyId: newHistoryId, updatedAt: new Date().toISOString() }));
              }
              saveCheckpoint(CHECKPOINT_PATH, {
                lastKey: 'phase1_complete',
                processed: existing.length + (newMessages.length > 0 ? newMessages.length : 0),
                phase1CompletedAt: new Date().toISOString(),
                indexPath: INDEX_30D_PATH,
                source: 'partial_sync',
                lastHistoryId: newHistoryId,
              });
            }
          } catch (histErr: any) {
            if (histErr?.code === 404 || String(histErr).includes('404')) {
              // historyId expired (Google keeps ~7 days) â€” full sync required
              console.log(`\n  historyId expired (404) â€” falling back to full sync`);
              // Clear the stale historyId so next run starts fresh
              if (!COORDINATED_FETCH) {
                try { require('node:fs').rmSync(HISTORY_ID_PATH); } catch { /* ok */ }
              }
              phase1ShouldFetch = true;
            } else {
              throw histErr;
            }
          }
        } else {
          // â”€â”€ State C: no historyId â€” call getProfile once (1 quota unit) to get cursor â”€â”€
          // This only happens on the very first run or after --force-phase1.
          // After this run, storedHistoryId is saved and State B runs on every subsequent run.
          try {
            const profile = await gmail.users.getProfile({ userId: 'me' });
            const freshHistoryId = profile.data.historyId ?? undefined;

            // DO NOT compare inWindow.length against messagesTotal â€” messagesTotal is the
            // ALL-TIME mailbox count (61k+), not the 90-day window count (10k). That
            // comparison always fails (17%) and triggers a full re-fetch every run.
            // The local index covers the --since window by definition. If it has messages,
            // it is sufficient. The historyId cursor handles new arrivals on next run.
            console.log(`\nPhase 1/4: Index has ${inWindow.length} messages in window â€” saving historyId for delta sync on next run.`);
            phase1ShouldFetch = false;

            // Always save historyId â€” enables State B on every subsequent run
            if (freshHistoryId) {
              upsertEmailCacheBatch(inWindow, emailCacheAccountId(account), since.toISOString());
              if (!COORDINATED_FETCH) {
                writeFileSync(HISTORY_ID_PATH, JSON.stringify({ historyId: freshHistoryId, updatedAt: new Date().toISOString() }));
              }
              saveCheckpoint(CHECKPOINT_PATH, {
                lastKey: 'phase1_complete',
                processed: inWindow.length,
                phase1MessagesCount: inWindow.length,
                phase1CompletedAt: new Date().toISOString(),
                indexPath: INDEX_30D_PATH,
                source: 'validated_existing',
                lastHistoryId: freshHistoryId,
              });
              console.log(`  historyId=${freshHistoryId} saved. Use --force-phase1 to re-fetch all.`);
            }
          } catch (err) { throw err; }
        }
      } else {
        // Offline or token expired â€” trust local index
        if (inWindow.length > 100) {
          console.log(`\nPhase 1/4: SKIP (offline) â€” using ${inWindow.length} messages from local index`);
          phase1ShouldFetch = false;
        }
      }
    } catch (indexCheckErr: any) {
      throw indexCheckErr;
    }
  }

  if (phase1ShouldFetch) {
    await phase1FetchGmailIndex({ account, since, until, limit, dryRun, offline, reset });
  } else if (!dryRun) {
    upsertEmailCacheBatch(readEmailIndexFile(INDEX_30D_PATH), emailCacheAccountId(account), since.toISOString());
  }

  // â”€â”€ Phase 1b: iMessage backfill (macOS ONLY â€” requires Full Disk Access) â”€â”€
  // Guard: darwin only â€” iMessage does not exist on Linux, WSL, or Windows.
  // process.platform === 'darwin' is the correct check (not !== 'win32', which
  // would also run on Linux/WSL where chat.db never exists).
  // Non-fatal: FDA denial, missing chat.db, and any runtime error are all caught and logged.
  if (!skipChannels && !enrichmentOnly && process.platform === 'darwin') {
    const chatDbPath = process.env.IMESSAGE_DB_PATH ||
      join(homedir(), 'Library', 'Messages', 'chat.db');
    if (existsSync(chatDbPath)) {
      console.log('\nPhase 1b: iMessage backfill...');
      try {
        const { backfillBulk } = await import('./extensions/imessage-triage/backfill-bulk.ts') as any;
        if (typeof backfillBulk === 'function') {
          const imsgResult = await backfillBulk({
            since: since?.toISOString().split('T')[0] ?? new Date(Date.now() - 90 * 86400000).toISOString().split('T')[0],
            limit,
          });
          console.log(`  âœ“ iMessage: ${imsgResult.processed ?? 0} episodes, ${imsgResult.people ?? 0} people (${imsgResult.elapsed ?? 0}ms)`);
        }
      } catch (e: any) {
        if (e?.code === 'FDA_DENIED') {
          console.warn('  âš  iMessage: Full Disk Access not granted â€” skipped');
          console.warn('    Grant FDA to Terminal/iTerm in System Settings â†’ Privacy â†’ Full Disk Access');
        } else {
          console.warn(`  âš  iMessage backfill error (non-fatal): ${e?.message?.slice(0, 120)}`);
        }
      }
    } else {
      console.log('\nPhase 1b: iMessage â€” skipped (chat.db not found at ' + chatDbPath + ')');
    }
  } else if (enrichmentOnly) {
    console.log('\nPhase 1b: iMessage â€” skipped (--enrichment-only: channel fetches disabled)');
  } else if (skipChannels) {
    console.log('\nPhase 1b: iMessage â€” skipped (--skip-channels)');
  } else if (process.platform !== 'darwin') {
    console.log('\nPhase 1b: iMessage â€” skipped (macOS only, current platform: ' + process.platform + ')');
  }

  if (COORDINATED_FETCH) {
    stageCanonicalEmailBatches();
    _forensicWrite({ event: 'canonical_spool_pending', status: 'ok' });
    await new Promise<void>(resolve => process.stdout.write('', () => resolve()));
    process.exit(0);
  }
  } // end Phase 1 source sync

  // â”€â”€ Schema bootstrap â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Apply all Graph indexes and uniqueness constraints before any graph writes.
  // Skipped on incremental runs where schema is already current â€” the schemaVersion
  // stamp in the checkpoint tracks whether the schema has been applied.
  // Only runs when: first ever run, or schema steps changed (new indexes added).
  // Source: graph.com/docs/fundamentals/indexing
  // SCHEMA_VERSION: bump this string whenever PROPERTY_INDEXES, TEXT_INDEXES, VECTOR_INDEXES,
  // or BACKFILL_STEPS arrays change. Use a date-stamped identifier rather than a step count â€”
  // step counts become wrong the moment any step is added or removed, causing the checkpoint
  // to falsely match and skip the entire migration on every subsequent run.
  // Format: 'v2-YYYY-MM-<batch>' where batch is a letter suffix for same-month changes.
   const SCHEMA_VERSION = 'v2-2026-07-j'; // fix: node2vec_embedding index property name (was camelCase); T3.8 ML enrichment wired
  const schemaAlreadyApplied = checkpoint?.schemaVersion === SCHEMA_VERSION;
  if (!dryRun && !schemaAlreadyApplied) {
    try {
       const { migrateSchemaV2 } = await import('./lib/triage-core/graph/schema-v2.ts');
       const schemaResult = await migrateSchemaV2();
       const newSteps = schemaResult.steps.filter(s => s.status === 'success');
       if (newSteps.length > 0) {
         console.log(`\nSchema: applied ${newSteps.length} new index/constraint(s): ${newSteps.map(s => s.name).join(', ')}`);
         // ANALYZE GRAPH after new indexes â€” recalculates distribution stats for query planner
         // Source: graph.com/docs/fundamentals/indexes#analyze-graph
         // Without this, the planner may not use new indexes until statistics are refreshed.
         try {
           const { rawWrite: _analyzeRw } = _require('./lib/graph/graph-transport.js') as any;
           await _analyzeRw('ANALYZE GRAPH');
           console.log('  âœ“ ANALYZE GRAPH: planner statistics updated');
         } catch { /* non-fatal */ }
       } else {
         console.log(`\nSchema: all indexes/constraints already current (${schemaResult.skipped} skipped)`);
       }
       if (schemaResult.failed > 0) {
         console.warn(`  âš  ${schemaResult.failed} schema step(s) failed (non-fatal â€” backfill will continue)`);
       }
      // Stamp the checkpoint so subsequent runs skip schema entirely
      saveCheckpoint(CHECKPOINT_PATH, {
        ...(loadCheckpoint(CHECKPOINT_PATH) ?? {}),
        schemaVersion: SCHEMA_VERSION,
      });
    } catch (e: any) {
      console.warn(`  âš  Schema migration failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }
  } else if (!dryRun) {
    console.log(`\nSchema: current (${SCHEMA_VERSION}) â€” skipping`);
  }

  // â”€â”€ Phase 2: Ingest to graph â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Always re-runs â€” Phase 2 is idempotent (MERGE semantics; existing nodes are updated,
  // not duplicated). Skipping it would mean config changes to the ingest pipeline are
  // never picked up without manual --reset.
  await phase2IngestToGraph(dryRun, account?.email, since?.toISOString());


  // â”€â”€ Phase 3: Triage + Draft â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Phase 3 runs in checkpointed batches of PHASE3_CHUNK_SIZE emails.
  // Use --phase3-reset to clear the batch checkpoint and restart from offset 0.
  //
  // Pre-warm the tournament process pool before Phase 3 starts.
  // The pool starts up to MAX_WORKERS (default 3) elyntic-rpc processes in the
  // background while we print the config header. Each process pays the 15â€“60s
  // jiti startup cost once; all subsequent tournament judge calls reuse warm slots.
  // Without pre-warming, the first tournament fires cold mid-classify and the 180s
  // global timeout hits before the first result arrives.
  if (!dryRun) {
    console.log('\nPre-warming tournament process pool...');
    console.log(`  Waiting for [elyntic-rpc] rpc_ready signal on each slot (up to ${process.platform === 'win32' ? '120s on Windows NTFS' : '30s'}).`);
    try {
      const { prewarmTournamentPool } = require('./lib/triage-core/tournament-runner');
      await prewarmTournamentPool();
      console.log('  âœ“ Tournament pool warm â€” all slots confirmed rpc_ready');
    } catch (e: any) {
      console.warn(`  âš  Pool pre-warm failed: ${e?.message?.slice(0, 80)} â€” tournaments will cold-start`);
    }
  }

  // â”€â”€ Ensure self-person node exists before Phase 3 â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // getMeContext() (called inside entity-extractor.ts ensureInitialized()) reads
  // the Me node from the graph to build relationship context for Qwen3 prompts.
  // If the node is absent, _meContextPrompt is empty and Qwen3 gets no context â€”
  // degrading urgency boosting, Dunbar-layer tagging, and all relationship signals.
  // This runs even if ELYNTIC_SELF_ID is a Gmail address (it still works as a node ID).
  if (!dryRun) {
    try {
      await ensureSelfPerson();
    } catch (e: any) {
      console.warn(`  âš  ensure-self-person failed: ${e?.message?.slice(0, 120)}`);
      console.warn('  getMeContext() will return empty context â€” Qwen3 extraction quality will be degraded.');
      console.warn('  Set ELYNTIC_SELF_ID and ELYNTIC_SELF_NAME in .env and re-run to fix.');
    }
  }

  } // end Phases 1+2 block

  // â”€â”€ Phase 2.5: Full Enrichment Pipeline â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Skipped with --skip-enrichment (fast daily path).
  // Always runs with --enrichment-only (nightly batch path).
  // Otherwise runs after every sync+ingest.
  //
  // Runs the complete enrichment suite BEFORE Phase 3 triage so all 34 signals
  // have real data. Without this, ~15 signals return neutral/zero defaults.
  // BACKFILL-GRAPH-SWEEP-1: Phase 2.5 is gated on the legacy graph opt-in.
  //
  // Every step in this block (T0-A..T0-E, T1-A..T1-F, T3.5-A..D, T4-A..E,
  // T4.5-A..C) was measured to be bolt-bound with no SQL fallback. The
  // sql-graph-fallback shim only pattern-matches a few point lookups
  // (person-by-id, person-by-email, agent-by-id) while every query here is a
  // multi-hop match or aggregation, so rawRead throws rather than degrading.
  //
  // The gate is placed OUTSIDE the block rather than inside each step on
  // purpose: the very first statement of the block is
  //   require('./lib/graph/graph-transport.js')
  // whose broker auto-connects on require. Guarding the steps individually
  // would still have opened the connection.
  //
  // Skipping is reported in full (renderGraphDegradationReport lists every
  // capability that did not run) rather than silently, so a graph-free backfill
  // is honestly partial instead of looking like a complete one.
  if (!dryRun && !skipEnrichment && !legacyGraphEnabled()) {
    console.log();
    console.log('Phase 2.5/4: Running SQLite-native analytical enrichment engine (34 signals)...');
    sendIPC({ type: 'phase', ts: Date.now(), phase: '2.5', label: 'Enrichment (SQLite native)', state: 'running' });
    try {
      const { resolveAgentStorePath } = require('./lib/desktop-db-path.js');
      const Database = require('better-sqlite3');
      const dbPath = resolveAgentStorePath();
      const db = new Database(dbPath, { timeout: 5000 });
      const { runSqlBackfillEnrichment } = require('./lib/triage-core/sql-backfill-enrichment.ts');
      const { resolveSelfId } = await import('./lib/triage-core/self-identity.ts');
      const resolvedSelfId = await resolveSelfId(selfEmail);
      const res = runSqlBackfillEnrichment(db, { selfId: resolvedSelfId ?? '', selfEmail });
      console.log(`  ✓ SQLite enrichment complete: ${res.personsEnriched} persons, ${res.edgesEnriched} edges in ${res.elapsedMs}ms`);
      db.close();
      sendIPC({ type: 'phase', ts: Date.now(), phase: '2.5', label: 'Enrichment (SQLite native)', state: 'done', elapsed: res.elapsedMs });
    } catch (e: any) {
      console.warn(`  ⚠️ SQLite enrichment fallback warning: ${e?.message}`);
      sendIPC({ type: 'phase', ts: Date.now(), phase: '2.5', label: 'Enrichment (partial)', state: 'done', elapsed: 0 });
    }
  }

  if (!dryRun && !skipEnrichment && legacyGraphEnabled()) {
    console.log('\nPhase 2.5/4: Full enrichment pipeline (all 34 signal dependencies)...');
    sendIPC({ type: 'phase', ts: Date.now(), phase: '2.5', label: 'Enrichment', state: 'running' });
    const enrichStart = Date.now();

    const mg = (() => { try { return require('./lib/graph/graph-transport.js'); } catch { return null; } })();

    // mageWriteEarly: the write entry used by T0-A batch MERGEs and the T1 MAGE
    // steps. It runs through the graph transport: a plain write executes on the
    // store, a MAGE procedure call or a Graph admin statement is a counted
    // no-op that returns [] (see lib/graph/graph-transport.js). Returns rows.
    const mageWriteEarly = async (cypher: string, params?: Record<string, unknown>): Promise<any[]> => {
      const rows = await (mg as any).rawWrite(cypher, params ?? {});
      return Array.isArray(rows) ? rows : [];
    };

    // â”€â”€ Free memory before enrichment â€” reduces crash risk from Delta accumulation â”€â”€
    // Phase 2 creates ~10k nodes + 27k edges â€” each write creates Delta objects (56B each).
    // Calling FREE MEMORY forces GC before the enrichment pass which reads all those nodes.
    // Docs: https://graph.com/docs/fundamentals/storage-memory-usage#free-memory
    //
    // Enable gc-aggressive only for the duration of the FREE MEMORY call, then disable.
    // Aggressive GC takes an exclusive lock â€” beneficial here (no concurrent txs yet)
    // but harmful during Phase 2.5 parallel enrichment writes (causes stalls + conflicts).
    // Source: graph.com/docs/fundamentals/storage-memory-usage
    //   "storage-gc-aggressive acquires an exclusive lock, briefly blocks all transactions"
    if (mg?.rawWrite) {
      try {
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "true"');
        await mg.rawWrite('FREE MEMORY');
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "false"');
        process.stdout.write('  ðŸ§¹ FREE MEMORY called â€” GC complete\n');
      } catch { /* non-fatal */ }
    }

     // Enable slow query logging for Phase 2.5 â€” log queries taking >1s to Graph log.
     // Source: graph.com/docs/database-management/logs#slow-and-failed-query-logging
     //   SET DATABASE SETTING "log.min_duration_ms" TO "1000" â€” logs queries >1s.
     //   SET DATABASE SETTING "log.failed_queries" TO "true" â€” logs failed queries.
     // These persist between runs. Check /var/log/graph/ for [slow-query] and [failed-query] lines.
     if (mg?.rawWrite) {
       try {
         await mg.rawWrite('SET DATABASE SETTING "log.min_duration_ms" TO "1000"');
         await mg.rawWrite('SET DATABASE SETTING "log.failed_queries" TO "true"');
       } catch { /* non-fatal â€” older Graph versions may not support these settings */ }
     }

    // â”€â”€ Write-readiness probe â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // Graph enters transient read-only mode after WAL replay.
    // Also, Phase 2 writes 10k nodes + edges which triggers WAL flush and a
    // potential snapshot â€” Graph may briefly drop connections during this.
    // Probe with a real write query, retrying on ANY error (ECONNREFUSED,
    // read-only, storage lock) up to 30x with 3s backoff = 90s max wait.
    if (mg?.rawWrite) {
      console.log('  Waiting for Graph write-readiness after Phase 2...');
      let writeReady = false;
      for (let attempt = 0; attempt < 30; attempt++) {
        try {
          await mg.rawWrite('CREATE (n:_WriteProbe {ts: timestamp()}) DELETE n');
          writeReady = true;
          if (attempt > 0) console.log(`  âœ“ Graph write-ready after ${attempt * 3}s`);
          break;
        } catch (e: any) {
          if (attempt < 29) {
            if (attempt === 0 || attempt % 5 === 0)
              process.stdout.write(`  Waiting for Graph (attempt ${attempt + 1}/30, 3s backoff)...\n`);
            await new Promise(r => setTimeout(r, 3000));
            // Reconnect: reset the driver so next attempt uses a fresh connection
            try { if (mg.resetDriver) await mg.resetDriver(); } catch { /* non-fatal */ }
          }
        }
      }
      if (!writeReady) console.warn('  âš  Graph not write-ready after 90s â€” proceeding anyway');
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 0 â€” Graph structure prerequisites
    // Must run before any enrichment. These create the Episode nodes and
    // self-anchored KNOWS edges that ALL downstream steps depend on.
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€

    // â”€â”€ Phase 2.5 step checkpoint â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // Persist which steps completed so a Graph restart mid-run can resume
    // from the failed step rather than re-running the whole pipeline.
    // Pattern from Graph docs: store state in a JSON file (WAL-independent).
    const PHASE25_CHECKPOINT = join(DATA_DIR, 'phase25-checkpoint.json');
    const _completedSteps = new Set<string>();
    try {
      // Load phase 2.5 step checkpoint so individual signal steps can resume
      // after a mid-run crash without re-running already-completed steps.
      // The checkpoint is cleared at the start of every full pipeline run
      // so config changes always take effect on the next run.
      if (existsSync(PHASE25_CHECKPOINT)) {
        const saved = JSON.parse(readFileSync(PHASE25_CHECKPOINT, 'utf-8'));
        (saved.completed || []).forEach((s: string) => _completedSteps.add(s));
        // Note: the set is cleared immediately below â€” these steps WILL re-run.
        // This message is informational only (shows what completed in the prior run).
        if (_completedSteps.size > 0) console.log(`  Prior run completed ${_completedSteps.size} steps (re-running all fresh): ${[..._completedSteps].join(', ')}`);
      }
    } catch { /* fresh start */ }
    // Always clear at start of run â€” ensures every full pipeline run re-evaluates all steps
    writeFileSync(PHASE25_CHECKPOINT, JSON.stringify({ completed: [] }));
    _completedSteps.clear();

    const markStepDone = (step: string) => {
      _completedSteps.add(step);
      try { writeFileSync(PHASE25_CHECKPOINT, JSON.stringify({ completed: [..._completedSteps] })); } catch { /* non-fatal */ }
    };
    const stepDone = (step: string) => _completedSteps.has(step);

    // Wrapper: skip if already done, wait for Graph if needed, then run
    const runStep25 = async (id: string, label: string, fn: () => Promise<void>) => {
      if (stepDone(id)) { console.log(`  â­ ${label} â€” already completed (checkpoint)`); return; }
      const _t0 = Date.now();
      try {
        await fn();
        markStepDone(id);
        _forensicWrite({ event: 'step_ok', id, label, durationMs: Date.now() - _t0 });
      } catch (e: any) {
        const isConnErr = e?.message?.includes('ECONNREFUSED') || e?.message?.includes('Failed to connect');
        if (isConnErr) {
          const recovered = await waitForGraph(120_000, id);
          if (recovered) {
            try {
              await fn(); markStepDone(id);
              _forensicWrite({ event: 'step_ok', id, label, durationMs: Date.now() - _t0, retried: true });
              return;
            } catch { /* fall through to warn */ }
          }
        }
        _forensicWrite({ event: 'step_fail', id, label, durationMs: Date.now() - _t0, error: e?.message?.slice(0, 200) });
        console.warn(`  âš  ${label} failed (non-fatal): ${e?.message?.slice(0,80)}`);
      }
    };
    const selfId = process.env.ELYNTIC_SELF_ID || '';
    let selfEmail = process.env.ELYNTIC_SELF_EMAIL || '';

    // Fix: If ELYNTIC_SELF_EMAIL is not set, query the graph for the self-person's email.
    // The self-person node (Person {isSelf: true}) has p.email set by ensureSelfPerson()
    // and by Phase B backfill. Using the graph value means direction detection works
    // even without the env var, preventing all episodes from being marked 'inbound'.
    // Source: graph.com/docs/querying/clauses/match + COALESCE + split() pattern
    if (!selfEmail && mg) {
      try {
        const selfEmailResult = await mg.rawRead(
          `OPTIONAL MATCH (p:Person {isSelf: true}) RETURN coalesce(p.email, '') AS selfEmail LIMIT 1`
        ) as any[];
        const graphEmail = selfEmailResult?.[0]?.selfEmail ?? '';
        if (graphEmail && graphEmail.includes('@')) {
          selfEmail = graphEmail;
          process.stdout.write(`  âœ“ Self-email resolved from graph: ${selfEmail}\n`);
        }
      } catch { /* non-fatal â€” continue with empty selfEmail */ }
    }

    const selfDomains = selfEmail ? [selfEmail.split('@')[1]].filter(Boolean) : [];

    // T0-PRE: Self-ID unification
    // Phase 2 writes Person nodes with id = "person:email:<address>" format (canonical triage format).
    // ELYNTIC_SELF_ID is a UUID (193c12c6-...). These are two separate Person nodes for the
    // same person. ensureSelfPerson() creates the UUID node but does NOT link it to the
    // email:sha256 node. This step unifies them so enrichment queries anchored to ELYNTIC_SELF_ID
    // find all the Email/SENT_FROM/SENT_TO edges that Phase 2 wrote.
    //
    // Safety: guards against constraint violation â€” checks that $selfId is not already used
    // by a DIFFERENT node before overwriting. Tracks success for T0-B safety gate.
    let t0preSucceeded = false;
    if (mg?.rawWrite && selfId && selfEmail) {
      try {
        const { createRequire: _cr } = await import('module');
        const _safeReq = _cr(import.meta.url);
        const { rawRead: _rr } = _safeReq('./lib/graph/graph-transport.js') as any;
        const existing = await _rr(
          `MATCH (p:Person) WHERE toLower(p.email) = toLower($email) AND p.id <> $selfId
           RETURN p.id AS oldId LIMIT 1`,
          { email: selfEmail, selfId }
        );
        if (existing?.length > 0) {
          const oldId = existing[0].oldId;
          // Safety check: ensure $selfId is not already owned by a different Person node
          // (which would cause a Person.id UNIQUE constraint violation on the SET)
          const collision = await _rr(
            `MATCH (other:Person {id: $selfId}) WHERE other.email IS NULL OR toLower(other.email) <> toLower($email)
             RETURN count(other) AS n`,
            { selfId, email: selfEmail }
          );
          const collisionCount = collision?.[0]?.n?.toNumber?.() ?? Number(collision?.[0]?.n ?? 0);
          if (collisionCount > 0) {
            // UUID node already exists (ensureSelfPerson created it) â€” instead of overwriting
            // the email-derived node's id (which would collide), copy the email to the UUID node
            // Copying email/name does NOT give the UUID node the SENT_FROM/SENT_TO edges
            // Phase 2 wrote on the email node, which is this step's entire stated purpose
            // (see the block comment above). The SAME_AS link is what makes them reachable,
            // via query-time resolution. Because ensureSelfPerson() always runs before this
            // phase, the collision test above is always true, so this is the branch that
            // always runs -- and without the MERGE below it unified nothing while reporting
            // success. Measured 2026-07-28 on a live graph: the self node had 0 SENT_FROM,
            // 0 SENT_TO and 0 SAME_AS despite 98,619/104,120 edges on the email node.
            await mg.rawWrite(
              `MATCH (emailNode:Person {id: $oldId}), (uuidNode:Person {id: $selfId})
               SET uuidNode.email = COALESCE(uuidNode.email, emailNode.email),
                   uuidNode.name  = COALESCE(uuidNode.name, emailNode.name),
                   uuidNode.isSelf = true, uuidNode.dunbarLayer = 'me'
               MERGE (uuidNode)-[r:SAME_AS]->(emailNode)
               SET r.method = 'self_node_link', r.confidence = 'high'`,
              { oldId, selfId }
            );
            // Verify the link actually exists before reporting success, so the T0-B guard
            // below fires on real failure instead of being disarmed by an unconditional true.
            const selfLinked = await _rr(
              `MATCH (:Person {id: $selfId})-[r:SAME_AS]-(:Person {id: $oldId}) RETURN count(r) AS n`,
              { selfId, oldId }
            );
            const selfLinkCount = selfLinked?.[0]?.n?.toNumber?.() ?? Number(selfLinked?.[0]?.n ?? 0);
            t0preSucceeded = selfLinkCount > 0;
            console.log(`  T0-PRE: UUID self-node already exists - merged email/name from ${oldId} -> ${selfId}; SAME_AS link ${t0preSucceeded ? 'present' : 'MISSING'}`);
          } else {
            // Non-collision branch: rename the email-hash node's id to the UUID in-place.
            // Guard: only rename if no OTHER node already holds $selfId.
            // Replaces NOT EXISTS { MATCH ... } which triggers Graph filter-gen bug.
            // Uses OPTIONAL MATCH + WHERE IS NULL â€” the correct Graph-safe pattern.
            await mg.rawWrite(
              `MATCH (p:Person {id: $oldId})
               OPTIONAL MATCH (other:Person {id: $selfId})
               WHERE id(other) <> id(p)
               WITH p, other
               WHERE other IS NULL
               SET p.id = $selfId, p.isSelf = true, p.dunbarLayer = 'me', p._unifiedFromId = $oldId`,
              { oldId, selfId }
            );
            console.log(`  T0-PRE: Unified self-Person node: ${oldId} â†’ ${selfId}`);
            t0preSucceeded = true;
          }
        } else {
          console.log(`  T0-PRE: No email-derived self node to unify (self node already correct or not found)`);
          t0preSucceeded = true; // nothing to do = success
        }
      } catch (e: any) {
        console.warn(`  âš  T0-PRE: Self-ID unification failed â€” T0-B will warn about potential split identity: ${e?.message?.slice(0,100)}`);
      }
    }

    // T0-A: Email â†’ Episode conversion
    // Converts Email nodes (Phase 2) into Episode nodes needed by all downstream enrichment.
    //
    // Storage mode: IN_MEMORY_TRANSACTIONAL (default) â€” analytical mode REMOVED.
    //
    // Why analytical mode was removed:
    //   - The "6x faster + 0 Deltas" benefit requires >10M graph objects (docs).
    //   - T0-A converts ~42K Email nodes. Delta overhead = 42K Ã— 8 = ~340K Deltas = ~19MB.
    //     That is trivially small and does not warrant unique-access DDL.
    //   - STORAGE MODE IN_MEMORY_ANALYTICAL requires UNIQUE storage access â€” it blocks all
    //     other transactions. With broker background queries, watchdog, WAL replay etc.
    //     running concurrently, the access timeout fires before the mode switches.
    //   - Source: graph.com/docs/data-migration/best-practices
    //       "For datasets up to ~10M objects: single-threaded LOAD CSV is fine"
    //       "Batch size: 10Kâ€“100K per UNWIND batch" â€” already implemented below
    //   - Source: graph.com/docs/help-center/errors/transactions#storage-access-timeout
    //       "Cannot get unique access to the storage" â€” the exact error we were hitting
    //
    // The parallel 4-worker UNWIND pattern below handles Deltas correctly:
    //   - Each worker processes 5K mids per batch â†’ ~40K Deltas per commit â†’ GC cleans between batches
    //   - MERGE is idempotent â†’ re-run after any failure produces correct results
    //   - mageWriteEarly is a transport write with no JS-side semaphore
    //
    if (mg?.rawWrite && selfId) {
      console.log('  T0-A: Converting Email nodes â†’ Episode nodes...');

      // Step 1: wait until the graph transport answers
      let probeReady = false;
      for (let i = 0; i < 30; i++) {
        if (await probeGraph(5000)) {
          probeReady = true;
          if (i > 0) process.stdout.write(` ready after ${i * 2}s\n`);
          break;
        }
        if (i === 0) process.stdout.write('  Waiting for the graph store');
        else process.stdout.write('.');
        await new Promise(r => setTimeout(r, 2000));
      }
      if (!probeReady) process.stdout.write(' (timed out — proceeding anyway)\n');

      // Step 2: FREE MEMORY â€” flush Delta GC from Phase 2 write storm
      // Phase 2 created ~19MB of Delta objects. FREE MEMORY reclaims query execution
      // memory so the batch loop starts with a clean slate.
      // Source: graph.com/docs/fundamentals/storage-memory-usage â€” FREE MEMORY
      // gc-aggressive enabled only for the FREE MEMORY call duration (takes exclusive lock).
      try {
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "true"');
        await mg.rawWrite('FREE MEMORY');
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "false"');
        process.stdout.write('  ðŸ“Š FREE MEMORY: Delta GC flushed\n');
      } catch { /* non-fatal */ }

      // Step 2: FREE MEMORY â€” flush Delta GC from Phase 2 write storm
      try {
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "true"');
        await mg.rawWrite('FREE MEMORY');
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "false"');
        process.stdout.write('  ðŸ“Š FREE MEMORY: Delta GC flushed\n');
      } catch { /* non-fatal */ }

      // Step 3: Parallel batch loop â€” transactional mode, 4 workers, 5K UNWIND batches.
      // Source: graph.com/docs/data-migration/best-practices
      //   "Chunk size: 10,000â€“100,000 elements per UNWIND batch"
      //   "Running batches in parallel" â€” Promise.all with one session per branch
      //
      // Worker concurrency: 4 â€” conservative, avoids overwhelming Graph.
      // Batch size: 5000 mids per UNWIND â€” reduces round-trips 9x vs 500.
      //
      // Worker concurrency: 4 (conservative â€” avoids overwhelming Graph on commodity hardware)
      // Batch size: 5000 mids per UNWIND (raised from 500 â€” reduces round-trips 9x)
       let totalEpisodes = 0;
       try {
         // Use index scan via label â€” WITH Email(messageId) index this is O(N) index scan
         // instead of full ScanAll + Filter. Index on :Email(messageId) added in schema v2-2026-07-i.
         const emailRows = await mg.rawRead(
           `MATCH (e:Email) WHERE e.messageId IS NOT NULL RETURN e.messageId AS mid`
         ) as any[];
        const allMids = [...new Set(
          emailRows
            .map((r: any) => r.mid)
            .filter((v: any) => v != null && v !== 'null' && String(v).trim() !== '')
            .map((v: any) => String(v))
        )];
        process.stdout.write(`  ðŸ“§ ${allMids.length} unique Email nodes to convert\n`);

        const T0A_BATCH_SIZE = 5000; // raised from 500 â€” 9x fewer round-trips
        const T0A_WORKERS = 4;      // parallel sessions in analytical mode (thread-safe)
        // Twin guard: the orchestrator path creates episodes for the same
        // message under 'ep-email-gmail-<account>-<mid>' while T0-A uses
        // 'ep-email-<mid>' — two id conventions produced 92 duplicate-rawId
        // pairs. Skip creation when ANY episode already carries this rawId.
        const T0A_CYPHER = `UNWIND $mids AS mid
               MATCH (e:Email {messageId: mid})
               OPTIONAL MATCH (twin:Episode {rawId: mid})
               WITH e, mid, twin
               WHERE twin IS NULL OR twin.id = 'ep-email-' + mid
               MERGE (ep:Episode {id: 'ep-email-' + mid})
               ON CREATE SET
                 ep.text        = CASE
                   WHEN e.body IS NOT NULL AND size(e.body) > 10
                   THEN COALESCE(e.subject, '') + ' ' + e.body
                   ELSE COALESCE(e.subject, '') + ' ' + COALESCE(e.snippet, '')
                 END,
                 ep.platform    = 'email',
                 ep.messageType = 'email',
                 ep.direction   = CASE
                   WHEN size($selfDomains) > 0 AND e.from IS NOT NULL
                     AND ANY(d IN $selfDomains WHERE toLower(e.from) ENDS WITH ('@' + d))
                   THEN 'outbound'
                   WHEN $selfEmail <> '' AND e.from IS NOT NULL
                     AND toLower(e.from) = toLower($selfEmail)
                   THEN 'outbound'
                   ELSE 'inbound'
                 END,
                 ep.receivedAt  = CASE
                   WHEN e.isoDate IS NOT NULL AND e.isoDate =~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*' THEN datetime(e.isoDate)
                   WHEN e.date IS NOT NULL AND e.date =~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*' THEN datetime(e.date)
                   ELSE NULL
                 END,
                 ep.rawId    = mid,
                 ep.createdAt = localdatetime()
                ON MATCH SET
                  ep.text     = CASE
                    WHEN e.body IS NOT NULL AND size(e.body) > 10
                      AND (ep.text IS NULL OR size(ep.text) < 100)
                    THEN COALESCE(e.subject, '') + ' ' + e.body
                    ELSE COALESCE(ep.text, COALESCE(e.subject, '') + ' ' + COALESCE(e.snippet, ''))
                  END,
                  ep.platform = COALESCE(ep.platform, 'email'),
                  ep.rawId    = COALESCE(ep.rawId, mid)
               SET ep:PersonDomain
               WITH ep, mid
               OPTIONAL MATCH (sender:Person)-[:SENT_FROM]->(e2:Email {messageId: mid})
               WITH ep, sender ORDER BY sender.id LIMIT 1
               FOREACH (_ IN CASE WHEN sender IS NOT NULL THEN [1] ELSE [] END |
                 MERGE (sender)-[:AUTHORED]->(ep)
               )
               RETURN count(ep) AS created`;

        // Split all mids into batches, then distribute across T0A_WORKERS worker queues
        const allBatches: string[][] = [];
        for (let i = 0; i < allMids.length; i += T0A_BATCH_SIZE) {
          allBatches.push(allMids.slice(i, i + T0A_BATCH_SIZE));
        }

        // Each worker gets a slice of the batches and processes them serially
        // Workers run concurrently with each other via Promise.all
        const workerSlices: string[][][] = Array.from({ length: T0A_WORKERS }, () => []);
        allBatches.forEach((b, idx) => workerSlices[idx % T0A_WORKERS].push(b));

        const workerResults = await Promise.all(
          workerSlices.map(async (sliceBatches, workerIdx) => {
            let workerCreated = 0;
            for (const batch of sliceBatches) {
              try {
                const result = await mageWriteEarly(
                  T0A_CYPHER,
                  { mids: batch, selfDomains, selfEmail: selfEmail.toLowerCase() }
                );
                workerCreated += result?.[0]?.created?.toNumber?.() ?? Number(result?.[0]?.created ?? 0);
              } catch (e: any) {
                const isConn = e?.message?.includes('ECONNREFUSED') || e?.message?.includes('Failed to connect');
                if (isConn) {
                  const recovered = await waitForGraph(60_000, `T0-A-worker-${workerIdx}`);
                  if (!recovered) {
                    console.warn(`  âš  T0-A worker ${workerIdx}: Graph did not recover`);
                    break;
                  }
                  // retry this batch once after recovery
                  try {
                    const retry = await mageWriteEarly(T0A_CYPHER, { mids: batch, selfDomains, selfEmail: selfEmail.toLowerCase() });
                    workerCreated += retry?.[0]?.created?.toNumber?.() ?? Number(retry?.[0]?.created ?? 0);
                  } catch { /* skip â€” MERGE is idempotent, will be caught on re-run */ }
                }
                // Skip non-connection errors â€” MERGE idempotency means re-run catches them
              }
            }
            return workerCreated;
          })
        );
        totalEpisodes = workerResults.reduce((a, b) => a + b, 0);
      } catch (err: any) {
        process.stderr.write(`  âš  T0-A: Fatal error: ${err?.message?.slice(0,100)}\n`);
      }

      // Step 4: FREE MEMORY after batch writes â€” frees Delta objects created during T0-A.
      // In transactional mode, each MERGE creates ~8 Delta objects (56B each).
      // 42K emails Ã— 8 Deltas = ~340K Deltas = ~19MB â€” small but worth freeing.
      // Source: graph.com/docs/fundamentals/storage-memory-usage â€” FREE MEMORY
      try {
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "true"');
        await mg.rawWrite('FREE MEMORY');
        await mg.rawWrite('SET DATABASE SETTING "storage-gc-aggressive" TO "false"');
      } catch { /* non-fatal */ }

      console.log(`  âœ“ T0-A: ${totalEpisodes} Episode nodes created from Email nodes`);
      sendIPC({ type: 'metric', ts: Date.now(), key: 'episodes', value: totalEpisodes });
      sendIPC({ type: 'step', ts: Date.now(), step: 'T0-A', state: 'done', value: totalEpisodes });

      // T0-A-RECV: Backfill receivedAt on any Episode that got NULL from the T0-A CASE.
      // Both T0-A and this step only convert ISO-8601 date strings — Graph's datetime()
      // throws on RFC 2822 ("Wed, 24 Jun 2026 ...") and one bad row fails the whole batch.
      // Episodes whose Email only has an RFC 2822 date stay NULL here and are repaired by
      // scripts/backfill-rfc2822-dates.ts, which parses them in JS.
      if (mg?.rawWrite) {
        try {
          const recv = await mg.rawWrite(
            `MATCH (ep:Episode {platform: 'email'})
             WHERE ep.receivedAt IS NULL AND ep.rawId IS NOT NULL
             MATCH (e:Email {messageId: ep.rawId})
             WHERE e.isoDate IS NOT NULL OR e.date IS NOT NULL
             SET ep.receivedAt = CASE
               WHEN e.isoDate IS NOT NULL AND e.isoDate =~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*' THEN datetime(e.isoDate)
               WHEN e.date IS NOT NULL AND e.date =~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*' THEN datetime(e.date)
               ELSE NULL
             END
             RETURN count(ep) AS fixed`
          );
          const fixed = recv?.[0]?.fixed?.toNumber?.() ?? Number(recv?.[0]?.fixed ?? 0);
          if (fixed > 0) console.log(`  âœ“ T0-A-RECV: ${fixed} Episode.receivedAt values backfilled from Email date fields`);
        } catch (e: any) {
          console.warn(`  âš  T0-A-RECV: receivedAt backfill failed (non-fatal): ${e?.message?.slice(0,100)}`);
        }
      }
      // T0-A's UNWIND only uses Email.messageId to create the Episode and links the SENDER via SENT_FROM.
      // But for INBOUND emails: sender=contact, recipient=self â€” the contact's AUTHORED edge is already
      // written in T0-A's OPTIONAL MATCH (sender:Person)-[:SENT_FROM]->(e2:Email {messageId: mid}).
      // What's MISSING: emails where self is the sender (outbound) â€” the self-person's AUTHORED edge.
      // Also missing: any Email with no SENT_FROM edge (rare but possible).
      // The schema-v2.ts BACKFILL_STEP for orphaned Episodes via Email.messageId covers the second case.
      // The first case is handled by T0-A itself (sender=self via selfDomains direction check).
      // âœ… No additional step needed â€” the gap analysis was incorrect.
      // The AUTHORED edge is created in T0-A for EVERY email's primary sender regardless of direction.
    } else {
      console.warn('  âš  T0-A: skipped â€” ELYNTIC_SELF_ID not set or Graph unavailable');
    }


    // T0-CLEANUP: Remove artifact Person nodes with null or legacy self-* IDs.
    // These are created by old pipeline versions and cause Dunbar/FAVEE skips.
    // - null-ID Person nodes: created when email header parsing produced no sender address
    // - self-* ID nodes: legacy format from pre-UUID era (e.g. self-1778964268905)
    if (mg?.rawWrite) {
      try {
        const cleaned = await mg.rawWrite(
          `MATCH (p:Person)
           WHERE p.id IS NULL OR p.id STARTS WITH 'self-'
           DETACH DELETE p
           RETURN count(p) AS removed`
        );
        const removed = cleaned?.[0]?.removed?.toNumber?.() ?? Number(cleaned?.[0]?.removed ?? 0);
        if (removed > 0) console.log(`  âœ“ T0-CLEANUP: removed ${removed} artifact Person nodes (null/self-* IDs)`);
      } catch (e: any) {
        console.warn(`  âš  T0-CLEANUP: artifact cleanup failed (non-fatal): ${e?.message?.slice(0,100)}`);
      }
    }

    // T0-B through T1-F: wrap each step with runStep25 for checkpoint + auto-retry
    // If Graph restarts mid-pipeline, waitForGraph() reconnects and retries
    // only the failed step â€” already-completed steps are skipped via checkpoint file.

    // Guard: T0-A must have created episodes before T1+ signal chain runs.
    // If T0-A produced 0 episodes (Graph crash mid-T0-A), all downstream
    // FAVEE/Dunbar/quality/commsStyle signals will compute from empty data.
    // ISSUE-A fix: promote from warn-and-continue to HARD ABORT.
    // T0-A writes Episode nodes in IN_MEMORY_ANALYTICAL mode. If the storage mode
    // restore times out or Graph crashes, the 0-node state is persisted and every
    // downstream signal silently returns zero/null. A hard abort here prevents the
    // pipeline from appearing to succeed while producing corrupt signal data.
    // Source: graph.com/docs/fundamentals/storage-memory-usage â€” analytical mode
    //         data is not durable; read-back verification is required after mode restore.
    //
    // BUG-3 FIX: Use mageWriteEarly (transport write) for the episode count
    // verification. Previously this used mg.rawRead which routes through the broker.
    // The broker pool was at 600%+ pressure during T0-A â€” rawRead timed out and
    // returned [] â†’ episodeCountInGraph = 0 â†’ false hard abort, even when T0-A
    // had written episodes successfully. mageWriteEarly bypasses the semaphore entirely.
    let episodeCountInGraph = 0;
    try {
      const epCheck = await mageWriteEarly('MATCH (e:Episode) RETURN count(e) AS n') as any[];
      episodeCountInGraph = epCheck?.[0]?.n?.toNumber?.() ?? Number(epCheck?.[0]?.n ?? 0);
    } catch {
      // If mageWriteEarly also fails, try rawRead as a last resort before aborting
      try {
        const epCheck2 = await mg.rawRead('MATCH (e:Episode) RETURN count(e) AS n') as any[];
        episodeCountInGraph = epCheck2?.[0]?.n?.toNumber?.() ?? Number(epCheck2?.[0]?.n ?? 0);
      } catch { /* non-fatal â€” proceed with 0 which will trigger the abort below */ }
    }
    if (episodeCountInGraph === 0) {
      const msg = [
        '  âœ— T0-A produced 0 Episode nodes in graph â€” ABORTING T1+ signal chain.',
        '    FAVEE, Dunbar, strength, quality, and commsStyle signals will all be zero/null.',
        '    Root cause: T0-A batch writes may have failed â€” check Graph connection and memory.',
        '    Recovery: Re-run with --reset to retry T0-A from scratch.',
      ].join('\n');
      console.error(msg);
      // Throw to skip the entire T1+ block. The outer catch will handle cleanup.
      throw new Error('T0-A-ZERO-EPISODES: Episode node count is 0 after T0-A â€” aborting T1+ to prevent corrupt signal data');
    } else {
      console.log(`  âœ“ Episode gate: ${episodeCountInGraph} Episode nodes confirmed in graph`);
    }

    // T0-PRE-B: Re-anchor Phase 2 KNOWS edges from email-hash self node to UUID self node.
    // Phase 2 (backfill.ts Phase D) creates KNOWS edges anchored to the sender's email-hash id.
    // T0-B creates new selfâ†’contact KNOWS from the UUID self node, but doesn't migrate
    // the 820 existing edges. This step copies them so the UUID node has full coverage.
    //
    // When this is a NO-OP: If T0-PRE took the non-collision branch (UUID did not exist yet),
    // T0-PRE renamed the email-hash node's .id field to the UUID in-place. That node IS the
    // UUID self node now, so T0-PRE-B correctly finds 0 old-self KNOWS edges to migrate.
    // In this case the Phase D KNOWS edges already point from the correct UUID node.
    //
    // When migration IS needed: If T0-PRE took the collision branch (UUID node already existed
    // from a prior ensureSelfPerson() call), the email-hash node still has its original ID and
    // its Phase D KNOWS edges need to be copied to the UUID node. T0-PRE-B handles this case.
    if (mg?.rawWrite && selfId && selfEmail) {
      await runStep25('T0-PRE-B', 'T0-PRE-B: Re-anchor KNOWS edges to UUID self node', async () => {
        const result = await mg.rawWrite(
          `MATCH (oldSelf:Person)
           WHERE toLower(oldSelf.email) = toLower($selfEmail)
             AND oldSelf.id <> $selfId
           MATCH (oldSelf)-[k:KNOWS]->(contact:Person)
           MATCH (newSelf:Person {id: $selfId})
           WHERE NOT (newSelf)-[:KNOWS]->(contact)
           MERGE (newSelf)-[newK:KNOWS]->(contact)
           ON CREATE SET
             newK.source              = 'migrated_from_phase2',
             newK.since               = k.since,
             newK.episodeCount        = k.episodeCount,
             newK.lastMessageAt       = k.lastMessageAt,
             newK.metadataSignals     = k.metadataSignals,
             newK.metadataSignalsV2   = k.metadataSignalsV2,
             newK.compositeStrength   = k.compositeStrength,
             newK.favee               = k.favee,
             newK.faveeFormality      = k.faveeFormality,
             newK.faveeActiveness     = k.faveeActiveness,
             newK.faveeValence        = k.faveeValence,
             newK.faveeExchange       = k.faveeExchange,
             newK.faveeEquality       = k.faveeEquality,
             newK.faveeUpdatedAt      = k.faveeUpdatedAt,
             newK.hppCategory         = k.hppCategory,
             newK.canonicalType       = k.canonicalType,
             newK.qualityProfile      = k.qualityProfile,
             newK.healthStatus        = k.healthStatus,
             newK.accountType         = k.accountType,
             newK.createdAt           = localdatetime()
           RETURN count(newK) AS migrated`,
          { selfEmail, selfId }
        );
        const migrated = result?.[0]?.migrated?.toNumber?.() ?? Number(result?.[0]?.migrated ?? 0);
        console.log(`  âœ“ T0-PRE-B: ${migrated} KNOWS edges re-anchored to UUID self node (all properties migrated)`);
      });
    }

     // T0-B: Create selfâ†’contact KNOWS edges
    if (mg?.rawWrite && selfId) {
      if (!t0preSucceeded) console.warn('  âš  T0-B: T0-PRE did not complete successfully â€” KNOWS edges may anchor to a different node than Phase 2 edges.');
      console.log('  T0-B: Creating selfâ†’contact KNOWS edges...');
      await runStep25('T0-B', 'T0-B: KNOWS edges', async () => {
        // Create KNOWS edges for ALL Person nodes, not just those with AUTHORED episodes.
        // Previous version skipped 94 "orphan" Person nodes (recipients-only who appeared
        // in email headers but never sent). Including them ensures full enrichment coverage
        // and prevents 0-strength scores caused by missing KNOWS edges.
        // Safety guard against extreme scale only — must exceed the real contact count
        // (the graph already holds >10k persons; at LIMIT 5000 half got no KNOWS edge
        // and silently dropped out of every downstream enrichment step).
        const knowsResult = await mg.rawWrite(
          `MATCH (self:Person {id: $selfId}), (p:Person)
           WHERE p.id IS NOT NULL AND p.id <> $selfId
             AND NOT (self)-[:KNOWS]->(p)
           WITH self, p LIMIT ${parseInt(process.env.KNOWS_EDGE_CAP ?? '100000', 10)}
           MERGE (self)-[k:KNOWS]->(p)
           ON CREATE SET k.source = 'backfill', k.createdAt = localdatetime()
           RETURN count(p) AS created`,
          { selfId }
        );
        const created = knowsResult?.[0]?.created?.toNumber?.() ?? Number(knowsResult?.[0]?.created ?? 0);
        console.log(`  âœ“ T0-B: ${created} selfâ†’contact KNOWS edges created`);
      });
    }

      // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
      // T0-C-PRE: Migrate stale ZonedDateTime keyFactsAttemptedAt â†’ string
      // Prior code wrote keyFactsAttemptedAt = localdatetime() which
      // stores a ZonedDateTime. Current code uses localdatetime() (LocalDateTime).
      // Comparing ZonedDateTime < localdatetime($iso) throws:
      //   "Can't compare value of type zoned_date_time to value of type string"
      // Fix: convert all existing ZonedDateTime values to plain ISO strings
      // (YYYY-MM-DDThh:mm:ss) that are type-compatible with localdatetime() comparisons.
      // This is idempotent: strings pass through toString() unchanged.
      // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
      if (mg?.rawWrite) {
        await runStep25('T0-C-PRE', 'T0-C-PRE: normalize keyFactsAttemptedAt type', async () => {
          await mg.rawWrite(
            `MATCH (p:Person)
             WHERE p.keyFactsAttemptedAt IS NOT NULL
             WITH p,
                  split(split(split(toString(p.keyFactsAttemptedAt), '[')[0], '.')[0], '+')[0] AS normalized
             WHERE normalized <> toString(p.keyFactsAttemptedAt)
             SET p.keyFactsAttemptedAt = normalized
             RETURN count(p) AS migrated`
          );
          await mg.rawWrite(
            `MATCH (p:Person)
             WHERE p.keyFactsUpdatedAt IS NOT NULL
             WITH p,
                  split(split(split(toString(p.keyFactsUpdatedAt), '[')[0], '.')[0], '+')[0] AS normalized
             WHERE normalized <> toString(p.keyFactsUpdatedAt)
             SET p.keyFactsUpdatedAt = normalized
             RETURN count(p) AS migrated`
          );
          console.log('  âœ“ T0-C-PRE: keyFactsAttemptedAt/keyFactsUpdatedAt normalized to localdatetime-compatible strings');
        });
      }

      // T0-C: Backfill Person.totalInteractions and Person.lastInteractionAt
      // Datetime string normalization â€” Graph datetime() only accepts localdatetime
      // format (no timezone offset, no sub-second component):
      //   toString(ZonedDateTime)  â†’ "2026-07-01T22:48:36.000000+00:00[UTC]"
      //   split('[')[0]            â†’ "2026-07-01T22:48:36.000000+00:00"  (strip IANA zone)
      //   split('.')[0]            â†’ "2026-07-01T22:48:36+00:00"         (strip sub-seconds)
      //   split('+')[0]            â†’ "2026-07-01T22:48:36"               (strip +00:00 offset)
      // For negative offsets (split('+') keeps them), also handle '-' prefix on offset:
      //   Use substring(toString(e.receivedAt), 0, 19) to extract ISO-8601 prefix (YYYY-MM-DDThh:mm:ss)
       //   without chained split() calls. Faster than 3Ã— split() on every row.
       // Source: graph.com/docs/querying/best-practices â€” minimize per-row string computation
       // Source: graph.com/docs/fundamentals/data-types#localdatetime
       if (mg?.rawWrite) {
          await runStep25('T0-C', 'T0-C: totalInteractions', async () => {
            // lastInteractionAt is ZONED_DATE_TIME — max() over the datetime values
            // directly. The old substring(toString(...), 0, 19) wrote 19-char strings,
            // which truncated RFC 2822 receivedAt to "Wed, 24 Jun 2026 14" (lossy) and
            // re-polluted lastInteractionAt with strings after every backfill run.
            // CASE keeps count(e) over all episodes while max() skips non-datetime rows.
            await mg.rawWrite(
               `MATCH (p:Person)-[:AUTHORED]->(e:Episode)
                WHERE e.receivedAt IS NOT NULL
                WITH p, count(e) AS cnt,
                     max(CASE WHEN valueType(e.receivedAt) = 'ZONED_DATE_TIME' THEN e.receivedAt END) AS lastAt
                SET p.totalInteractions = toInteger(cnt),
                    p.lastInteractionAt = CASE WHEN lastAt IS NOT NULL THEN lastAt ELSE p.lastInteractionAt END
                RETURN count(p) AS updated`
            );
            console.log('  âœ“ T0-C: Person.totalInteractions + lastInteractionAt backfilled');
          });
       }

      // T0-D: same localdatetime normalization â€” strip IANA zone, sub-seconds, and TZ offset
      if (mg?.rawWrite && selfId) {
          await runStep25('T0-D', 'T0-D: KNOWS.episodeCount', async () => {
            await mg.rawWrite(
               `MATCH (self:Person {id: $selfId})-[k:KNOWS]->(p:Person)
                OPTIONAL MATCH (p)-[:AUTHORED]->(e:Episode)
                WHERE e.receivedAt IS NOT NULL
                WITH k, count(e) AS epCount,
                     max(CASE WHEN valueType(e.receivedAt) = 'ZONED_DATE_TIME' THEN e.receivedAt END) AS lastMsg
                SET k.episodeCount = toInteger(epCount),
                    k.lastMessageAt = CASE WHEN lastMsg IS NOT NULL THEN lastMsg ELSE k.lastMessageAt END
                RETURN count(k) AS updated`,
              { selfId }
            );
            console.log('  âœ“ T0-D: KNOWS.episodeCount + lastMessageAt synced');
          });
      }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 0-E â€” Organization inference from email domains
    // Creates Organization nodes for contacts with business email addresses
    // and links them via WORKS_AT edges.
    //
    // Strategy (from research):
    //   1. Extract email domain from Person.email
    //   2. Skip personal/consumer domains (gmail, yahoo, hotmail, etc.)
    //      Source: github.com/disposable-email-domains (CC0, 5.3k stars)
    //   3. Create/find Organization {domain} â€” dedup key is domain
    //   4. Infer org name from first domain label (e.g. 'acme.com' â†’ 'Acme')
    //   5. Create WORKS_AT with confidence=0.6 (domain inference, not verified)
    //
    // Family member detection:
    //   Contacts with personal domains are NOT linked to Organization nodes.
    //   Family members are identified by: personal domain + dunbarLayer='intimate'
    //   + no Organization link. KNOWS.relationshipType='family' can be set manually
    //   or inferred by warm-tick from contact metadata + LLM extraction.
    //
    // Docs: graph.com/docs/querying/functions (split, randomUUID, datetime)
    //       graph.com/docs/querying/clauses/merge
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    if (mg?.rawWrite) {
      await runStep25('T0-E', 'T0-E: Organization inference from email domains', async () => {
        const { PERSONAL_DOMAINS } = (() => {
          // Try _require first (createRequire relative to import.meta.url);
          // fall back to an absolute path in case tsx resolves import.meta.url differently.
          try { return _require('./lib/personal-email-domains.js') as any; } catch {}
          try { return require(join(__dirname, 'lib', 'personal-email-domains.js')) as any; } catch {}
          // If neither path works, return an empty set â€” all domains treated as business.
          console.warn('  âš  T0-E: personal-email-domains.js not loadable â€” treating all domains as business');
          return { PERSONAL_DOMAINS: new Set<string>() };
        })() as { PERSONAL_DOMAINS: Set<string> };
        const personalDomainList = [...PERSONAL_DOMAINS] as string[];

        // Batch process: find all Person nodes with business email addresses,
        // create Organization nodes, link with WORKS_AT
        // MERGE on domain guarantees idempotency â€” same org created once regardless
        // of how many contacts share it.
        const result = await mg.rawWrite(
          `MATCH (p:Person)
           WHERE p.email IS NOT NULL
             AND p.id IS NOT NULL
             AND NOT COALESCE(p.isSelf, false) = true
           WITH p, toLower(split(p.email, '@')[1]) AS domain
           WHERE domain IS NOT NULL
             AND NOT domain IN $personalDomains
           WITH p, domain,
                /* Use second-to-last domain label (TLD-1) not first label.
                   split('sub.company.com','.')[0] = 'sub' (wrong)
                   split('sub.company.com','.')[-2] = 'company' (correct)
                   For 2-label domains like 'company.com': [-2] = 'company' (also correct) */
                split(domain, '.')[-2] AS mainLabel
           WITH p, domain, toUpper(substring(mainLabel, 0, 1)) + substring(mainLabel, 1) AS inferredName
           MERGE (o:Organization {domain: domain})
           ON CREATE SET
             o.id         = randomUUID(),
             o.name       = inferredName,
             o.domain     = domain,
             o.source     = 'email_domain_inference',
             o.createdAt  = datetime()
           ON MATCH SET
             o.updatedAt  = datetime()
           MERGE (p)-[r:WORKS_AT]->(o)
           ON CREATE SET
             r.inferredFrom  = 'email_domain',
             r.confidence    = 0.6,
             r.isPrimary     = true,
             r.createdAt     = datetime()
           RETURN count(DISTINCT o) AS orgsCreated, count(r) AS linksCreated`,
          { personalDomains: personalDomainList }
        );
        const orgsCreated = result?.[0]?.orgsCreated?.toNumber?.() ?? Number(result?.[0]?.orgsCreated ?? 0);
        const linksCreated = result?.[0]?.linksCreated?.toNumber?.() ?? Number(result?.[0]?.linksCreated ?? 0);
        console.log(`  âœ“ T0-E: ${orgsCreated} organizations inferred, ${linksCreated} WORKS_AT edges created`);

        // Also tag KNOWS edges with relationshipType based on domain.
        // personal domain + no org = 'personal' (may be family, friend, etc.)
        // business domain + org = 'professional'
        // This enables downstream signals to distinguish family from colleagues.
        if (selfId) {
          await mg.rawWrite(
            `MATCH (self:Person {id: $selfId})-[k:KNOWS]->(p:Person)
             WHERE k.relationshipType IS NULL AND p.email IS NOT NULL
             WITH k, p, toLower(split(p.email, '@')[1]) AS domain
             SET k.relationshipType = CASE
               WHEN domain IN $personalDomains THEN 'personal'
               ELSE 'professional'
             END`,
            { selfId, personalDomains: personalDomainList }
          );
          console.log('  âœ“ T0-E: KNOWS.relationshipType tagged (personal/professional)');
        }
      });
    }

    // â”€â”€ T0-ACCOUNT: Multi-account email source tagging â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // Tags all Email and Episode nodes with accountEmail so frontend can filter by source account.
    // Creates EmailAccount node and HAS_ACCOUNT relationship for the current account.
    // Dual-writes to SQL (email_accounts table) so the frontend can query without Graph.
    //
    // Key design choices:
    //   1. Email nodes get accountEmail/accountId from this account (current backfill run)
    //   2. Episode nodes get stamped via AUTHORED relationship (sender already has AUTHORED edge)
    //   3. EmailAccount node carries accountType: 'personal' | 'business' for company filtering
    //   4. SQL mirror written so frontend account selector works even during Graph downtime
    //
    // Multi-account filtering query (frontend):
    //   -- All accounts: no filter
    //   -- Single account: WHERE e.accountEmail = $accountEmail
    //   -- Company view: WHERE e.accountEmail IN $companyAccountEmails
    //
    // Source: graph.com/docs/data-modeling/best-practices â€” label-property index on accountEmail
    if (mg?.rawWrite && account && account.email) {
      try {
        const acctEmail = account.email;
        // Validate: email must contain '@' before domain extraction.
        // A malformed account email (display name passed instead of address) produces
        // empty acctDomain, which isPersonalDomain returns false for â†’ wrongly tagged 'business'.
        if (!acctEmail.includes('@')) {
          console.warn(`  âš  T0-ACCOUNT: account email "${acctEmail}" has no '@' â€” skipping account tagging`);
        } else {
        const acctId = `account-${acctEmail}`;
        const acctDomain = acctEmail.split('@')[1] || '';
        // Determine accountType using the canonical personal-domain list (same source as T0-E).
        // Using an inline subset here would diverge from T0-E and misclassify Proton Mail,
        // FastMail, AOL, and other personal providers as 'business' accounts.
        // Source: lib/personal-email-domains.js (CC0 disposable/personal domain list, 5k+ entries)
        const { isPersonalDomain: _isPD } = (() => {
          try { return _require('./lib/personal-email-domains.js'); }
          // Safe fallback: treat ALL domains as personal if the list can't load.
          // Failing open ('business') would misclassify every Gmail/Yahoo account as a
          // business account and trigger spurious HBO company lookups. Failing closed
          // ('personal') means business accounts are classified personal â€” visible and
          // correctable â€” rather than silently populating wrong company associations.
          catch { return { isPersonalDomain: (_d: string) => true }; }
        })() as { isPersonalDomain: (domain: string) => boolean };
        // The self-email domain is ALWAYS personal, regardless of the domain list.
        // personal-email-domains.js only covers known consumer providers (gmail, yahoo, etc.)
        // â€” it does not know about the user's own custom domain (e.g. example.com).
        // If the account being backfilled IS the self-person's own email, it's personal.
        // Check: if acctDomain matches the selfEmail domain, always classify as personal.
        const selfEmailDomain = selfEmail ? selfEmail.split('@')[1] : '';
        const acctType = (selfEmailDomain && acctDomain === selfEmailDomain)
          ? 'personal'
          : _isPD(acctDomain) ? 'personal' : 'business';

        // 1. Stamp all Email nodes that don't yet have accountEmail
        const stampEmailResult = await mg.rawWrite(
          `MATCH (e:Email)
           WHERE e.accountEmail IS NULL
           SET e.accountEmail = $acctEmail, e.accountId = $acctId
           RETURN count(e) AS stamped`,
          { acctEmail, acctId }
        );
        const emailsStamped = stampEmailResult?.[0]?.stamped?.toNumber?.() ?? Number(stampEmailResult?.[0]?.stamped ?? 0);

        // 2. Stamp Episode nodes that have an AUTHORED edge from the same sender as this account's emails
        //    Use the rawId (messageId) linkage: Email â†’ rawId â†’ Episode
        //    This is more accurate than the old SENT_FROM/SENT_TO traversal
        const stampEpResult = await mg.rawWrite(
          `MATCH (e:Email {accountEmail: $acctEmail})
           WHERE e.messageId IS NOT NULL
           MATCH (ep:Episode {rawId: e.messageId})
           WHERE ep.accountEmail IS NULL
           SET ep.accountEmail = $acctEmail, ep.accountId = $acctId
           RETURN count(ep) AS stamped`,
          { acctEmail, acctId }
        );
        const epsStamped = stampEpResult?.[0]?.stamped?.toNumber?.() ?? Number(stampEpResult?.[0]?.stamped ?? 0);

        // 3. Fallback: stamp email-platform Episodes authored by the account holder (selfId)
        //    that still lack accountEmail. Scoped to selfId to avoid confusing sender
        //    attribution with account ownership â€” external senders also have AUTHORED edges
        //    but their episodes belong to the account that RECEIVED the email, not their own.
        //    selfId is the account owner; their authored episodes are always stamped here.
        if (selfId) {
          await mg.rawWrite(
            `MATCH (self:Person {id: $selfId})-[:AUTHORED]->(ep:Episode)
             WHERE ep.platform = 'email' AND ep.accountEmail IS NULL
             SET ep.accountEmail = $acctEmail, ep.accountId = $acctId
             RETURN count(ep) AS stamped`,
            { acctEmail, acctId, selfId }
          );
        }

        const acctProvider = (account as any).provider ?? 'gmail';

        // 4. Create EmailAccount node + HAS_ACCOUNT from self
        await mg.rawWrite(
          `MERGE (a:EmailAccount {id: $acctId})
           SET a.email = $acctEmail,
               a.domain = $domain,
               a.accountType = $acctType,
               a.provider = $provider,
               a.updatedAt = localdatetime()
           WITH a
           MATCH (me:Person {id: $selfId})
           MERGE (me)-[:HAS_ACCOUNT]->(a)
           RETURN a.email AS account`,
          { acctId, acctEmail, domain: acctDomain, acctType, provider: acctProvider, selfId }
        );

        // Mailbox registration and company membership are Desktop-owned.
        // Backfill corpus capture must not create accounts or infer authority
        // from graph domain matches.

        console.log(`  âœ“ T0-ACCOUNT: ${acctEmail} (${acctType}) â€” ${emailsStamped} Email nodes, ${epsStamped} Episode nodes tagged`);
        } // end if (acctEmail.includes('@'))
      } catch (e: any) {
        console.warn(`  âš  T0-ACCOUNT: account tagging failed (non-fatal): ${e?.message?.slice(0, 100)}`);
      }
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 1 â€” MAGE graph algorithms
    // Wait for MAGE to be fully loaded before running any procedure.
    // mageWrite: alias of mageWriteEarly kept for the T1-A..T1-F call sites,
    // which do not use the return value. MAGE procedure calls are counted no-ops
    // on the LadybugDB transport (dialect sheet §4), so each T1 step completes
    // immediately and the signal it would have written stays null; the debt
    // census on /api/graph/health lists every one of them with its call site.
    const mageWrite = async (cypher: string, params?: Record<string, unknown>): Promise<void> => {
      await mageWriteEarly(cypher, params);
    };

    if (mg?.rawWrite) {
      // Disable server-side query timeout for MAGE algorithms (admin no-op on Ladybug)
      try { await mg.rawWrite('SET DATABASE SETTING "query.timeout" TO "0"'); } catch { /* non-fatal */ }
      // MAGE readiness: one bounded read. On the LadybugDB transport the
      // procedure catalogue call returns [], which reports MAGE as not loaded.
      let mageReady = false;
      try {
        const rows = await mg.rawRead('CALL mg.procedures() YIELD name WHERE name = "pagerank.get" RETURN name') as any[];
        mageReady = Array.isArray(rows) && rows.length > 0;
      } catch { /* not ready */ }
      if (!mageReady) process.stdout.write('  MAGE procedures not available on this graph engine — T1 algorithm steps run as no-ops\n');

      // Raise storage.access_timeout_sec before T1 MAGE analytical steps.
      // MAGE algorithms (pagerank, katz, clustering) hold shared storage locks for their
      // full execution duration. Without a generous timeout, concurrent GC or write
      // attempts hit "Cannot get read-only access" errors, cascade-fail, and crash the
      // watchdog via IPC timeout -> worker exit -1 -> broker dies -> all writes fail.
      try {
        const _mgT1 = (() => { try { return require('./lib/graph/graph-transport.js'); } catch { return null; } })() as any;
        if (_mgT1?.rawWrite) {
          // 60s is sufficient: pagerank/katz/degree complete in <10s each.
          // nxalg.clustering and leiden are skipped (SKIP_MAGE_CLUSTERING) so 300s not needed.
          // 300s was causing Graph to hold storage locks long enough to trigger a null-ptr
          // segfault in MAGE internals (Graph 3.11.0 bug).
          await _mgT1.rawWrite("SET DATABASE SETTING 'storage.access_timeout_sec' TO '60'");
          console.log('  [T1 pre-flight] storage.access_timeout_sec=60');
        }
      } catch { /* non-fatal */ }

      await runStep25('T1-A', 'T1-A: pageRank', async () => {
        // pagerank.get() optional first arg is a Graph projection (project() result).
        // Calling with positional numeric args like pagerank.get(100, 0.85, ...) causes
        // Graph to interpret 100 as the subgraph arg â†’ "Graph not found: graph".
        // Fix: call with no args to use defaults (max_iterations=100, damping=0.85, epsilon=1e-5).
        // Source: graph.com/docs/advanced-algorithms/available-algorithms/pagerank#get
        await mageWrite(`
          CALL pagerank.get()
          YIELD node, rank
          WITH node, rank
          WHERE "Person" IN labels(node) AND rank > 0
          SET node.pageRank = rank
          RETURN count(*) AS n`);
        console.log('  âœ“ T1-A: pageRank written');
      });
      // Inter-step pause: 2s between MAGE algorithm calls.
      // MAGE procedures are long-running transactions. After one completes, Graph's GC
      // cycle (storage-gc-cycle-sec=30) needs a brief window to release the transaction's
      // Delta objects and internal bookkeeping before the next algorithm starts.
      // Without this pause, back-to-back MAGE calls can trigger lock contention on the
      // internal transaction table, producing occasional "unable to acquire shared access"
      // errors on the second procedure.
      // Source: graph.com/docs/fundamentals/storage-access â€” shared vs unique access;
      //   consecutive analytical queries may briefly contend on the transaction registry.
      // 2s is sufficient for GC to start a cycle (gc-cycle-sec=30 but GC is also triggered
      // by transaction completion); enough to clear the lock contention window.
      await new Promise(r => setTimeout(r, 2000));

      // T1-B hard timeout: betweenness MAGE runs server-side with no client cancellation.
      // Override via T1B_TIMEOUT_MS env var. Default 600s matches the T3.8 MAGE steps —
      // the old 90s ceiling timed out on every run (9/9 in logs/backfill-forensic.jsonl)
      // because the step fell through to nxalg.betweenness_centrality() on the FULL graph
      // (~48K nodes, single-threaded Python/NetworkX). The Promise.race timeout does not
      // cancel the server-side query, so it kept holding shared storage access and starved
      // T1-C/T1-F ("Cannot get shared access to the storage").
      const T1B_TIMEOUT_MS = parseInt(process.env.T1B_TIMEOUT_MS ?? '600000', 10);
      // C++ MAGE betweenness is parallel; threads=4 matches the WSL2 vCPU ceiling
      // (default thread count is half of hardware threads — see BACKFILL-ADVERSARIAL-REVIEW R4-2).
      const T1B_THREADS = parseInt(process.env.T1B_THREADS ?? '4', 10);
      const _t1bTimeout = new Promise<never>((_, rej) => setTimeout(() => rej(new Error(`T1-B: betweenness step timeout (${T1B_TIMEOUT_MS / 1000}s)`)), T1B_TIMEOUT_MS));
       await runStep25('T1-B', 'T1-B: betweenness', () => Promise.race([_t1bTimeout, (async () => {
         // betweenness_centrality.get(graph, directed, normalized, threads) — CRITICAL:
         // scope to a Person+KNOWS projection. get() with NO projection runs over ALL
         // nodes (44K+ Episodes, Persons, Orgs, etc.) and is O(V*E) — never completes.
         // With the Person+KNOWS projection (~3,240 nodes × ~4,500 edges) it completes
         // in <1s (measured 0.28s on the live graph, 2026-07-08).
         //
         // NOTE: betweenness_centrality.get_subgraph() does NOT exist — the module has
         // exactly one procedure, get(directed, normalized, threads), which accepts an
         // optional projected graph as an implicit first argument (Graph C++ MAGE
         // graph-projection convention). The old get_subgraph() call failed instantly
         // with "unknown procedure" and fell through to the full-graph nxalg fallback,
         // which is the query that hung. That fallback is deliberately removed: on a
         // graph this size nxalg cannot finish inside any sane timeout, and betweenness
         // is non-critical (degreeCentrality from T1-F is the signal fallback).
         //
         // directed=false: KNOWS is matched undirected here, treat the projection as such.
         // Source: graph.com/docs/advanced-algorithms/available-algorithms/betweenness_centrality
         //   get(directed = true, normalized = true, threads = <half hw threads>)
         // Source: BACKFILL-ADVERSARIAL-REVIEW.md Finding R4-2.
         try {
           await mageWrite(`
             MATCH p=(a:Person)-[r:KNOWS]-(b:Person)
             WITH project(p) AS graph
             CALL betweenness_centrality.get(graph, false, true, ${T1B_THREADS})
             YIELD node, betweenness_centrality
             SET node.betweennessCentrality = betweenness_centrality
             RETURN count(*) AS n`);
         } catch (e1: any) {
           // Failed — betweenness is non-critical, degree_centrality is the signal fallback.
           // Do NOT fall back to nxalg.betweenness_centrality(): it runs on the full graph
           // single-threaded and is the exact query that wedged every previous run.
           console.log(`  ⭘ T1-B: betweenness unavailable (${e1?.message?.slice(0,60)}) — skipping`);
           return;
         }
         console.log('  ✓ T1-B: betweennessCentrality written');
        })()]));
      await new Promise(r => setTimeout(r, 2000));

      // T1-C: katz_centrality
      await runStep25('T1-C', 'T1-C: katz', async () => {
        // katz_centrality.get() â€” use no args (defaults: alpha=0.2, epsilon=0.01).
        // Positional numeric args are misinterpreted as Graph projection on some MAGE versions.
        try {
          await mageWrite(`
            CALL katz_centrality.get()
            YIELD node, rank
            WITH node, rank
            WHERE "Person" IN labels(node)
            SET node.katzCentrality = rank
            RETURN count(*) AS n`);
        } catch (e: any) {
          if (e?.message?.toLowerCase().includes('procedure') || e?.message?.toLowerCase().includes('unknown')
              || e?.message?.toLowerCase().includes('graph not found')) {
            console.log('  â­ T1-C: katz_centrality not in this MAGE build â€” skipping');
            return;
          }
          throw e;
        }
        console.log('  âœ“ T1-C: katzCentrality written');
      });
      await new Promise(r => setTimeout(r, 2000));

      // T1-D: nxalg.clustering segfaults Graph 3.11.0 under concurrent write load.
      // Skip when SKIP_MAGE_CLUSTERING=1 (set in .env). Re-enable after Graph/MAGE fix.
      if (process.env.SKIP_MAGE_CLUSTERING === '1') {
        console.log('  ⏭ T1-D: clusteringCoefficient — skipped (SKIP_MAGE_CLUSTERING=1, Graph 3.11 crash workaround)');
      } else {
      await runStep25('T1-D', 'T1-D: clustering', async () => {
        // Confirmed installed signature: nxalg.clustering(nodes LIST OF NODE, weight STRING?)
        // Collect Person nodes explicitly to scope to Person subgraph.
        // 10-minute hard timeout: nxalg.clustering on 3,000+ nodes can run >10 min.
        // Non-fatal if it times out — clusteringCoefficient just won't be written this run.
        const T1D_TIMEOUT_MS = 10 * 60 * 1000;
        const CONFLICT_DELAYS = [500, 1000, 2000];
        const runClustering = async () => {
          try {
            await mageWrite(`
              MATCH (n:Person)
              WITH collect(n) AS personNodes
              CALL nxalg.clustering(personNodes)
              YIELD node, clustering
              SET node.clusteringCoefficient = clustering
              RETURN count(*) AS n`);
          } catch (e1: any) {
            // Fallback: pass personNodes to avoid full-graph scan (same safety as primary path)
            await mageWrite(`MATCH (n:Person) WITH collect(n) AS personNodes CALL nxalg.clustering(personNodes) YIELD node, clustering SET node.clusteringCoefficient = clustering RETURN count(*) AS n`);
          }
        };
        let lastErr: any;
        for (let attempt = 0; attempt <= CONFLICT_DELAYS.length; attempt++) {
          try {
            await Promise.race([
              runClustering(),
              new Promise<never>((_, rej) => setTimeout(() => rej(new Error('T1-D clustering timeout (10min)')), T1D_TIMEOUT_MS)),
            ]);
            lastErr = null;
            break;
          } catch (e: any) {
            lastErr = e;
            const isTimeout = e?.message?.includes('timeout');
            if (isTimeout) {
              console.warn(`  ⚠ T1-D: clustering timed out after 10min — skipping`);
              return; // non-fatal skip
            }
            const isConflict = e?.message?.toLowerCase().includes('conflict') ||
                               e?.message?.toLowerCase().includes('conflicting') ||
                               e?.message?.toLowerCase().includes('deadlock');
            if (isConflict && attempt < CONFLICT_DELAYS.length) {
              await new Promise(r => setTimeout(r, CONFLICT_DELAYS[attempt]));
              continue;
            }
            throw e;
          }
        }
        if (lastErr) throw lastErr;
        console.log('  ✔ T1-D: clusteringCoefficient written');
      });
      } // end T1-D skip guard
      await new Promise(r => setTimeout(r, 2000));

      // T1-E: leiden_community_detection also segfaults Graph 3.11.0.
      // Skip when SKIP_MAGE_CLUSTERING=1.
      if (process.env.SKIP_MAGE_CLUSTERING === '1') {
        console.log('  ⏭ T1-E: communityId — skipped (SKIP_MAGE_CLUSTERING=1, Graph 3.11 crash workaround)');
      } else {
      await runStep25('T1-E', 'T1-E: leiden', async () => {
        // Confirmed installed signatures:
        //   leiden_community_detection.get_subgraph(nodes LIST, rels LIST, weight_property, ...)
        //   leiden_community_detection.get(weight_property STRING, gamma, theta, resolution, iterations)
        try {
          await mageWrite(`
            MATCH (n:Person)-[r:KNOWS]->(m:Person)
            WITH collect(DISTINCT n) + collect(DISTINCT m) AS nodes, collect(DISTINCT r) AS rels
            CALL leiden_community_detection.get_subgraph(nodes, rels, "weight", 1.0, 0.01, 0.01, 50)
            YIELD node, community_id
            SET node.communityId = community_id
            RETURN count(*) AS n`);
        } catch (e1: any) {
          try {
            await mageWrite(`
              CALL leiden_community_detection.get("weight", 1.0, 0.01, 0.01, 50)
              YIELD node, community_id
              WITH node, community_id WHERE "Person" IN labels(node)
              SET node.communityId = community_id
              RETURN count(*) AS n`);
          } catch (e2: any) {
            try {
              await mageWrite(`
                MATCH (n:Person)-[r:KNOWS]->(m:Person)
                WITH collect(DISTINCT n) + collect(DISTINCT m) AS nodes, collect(DISTINCT r) AS rels
                CALL community_detection.get_subgraph(nodes, rels)
                YIELD node, community_id SET node.communityId = community_id
                RETURN count(*) AS n`);
            } catch {
              try { await mageWrite('CALL community_detection.get() YIELD node, community_id WITH node, community_id WHERE "Person" IN labels(node) SET node.communityId = community_id RETURN count(*) AS n'); }
              catch { console.log('  â­ T1-E: community detection unavailable â€” skipping'); return; }
            }
          }
        }
        console.log('  âœ“ T1-E: communityId written');
      });
      } // end T1-E skip guard
      await new Promise(r => setTimeout(r, 2000));

      // T1-F: degree centrality
      // Correct MAGE proc: degree_centrality.get() YIELD node, degree (not get_degree_centrality)
      // Fallback: count only KNOWS edges (social degree), not ALL relationship types.
      // Counting all rels inflates degree by 10-100x (AUTHORED, SENT_FROM, WORKS_AT, etc.)
      await runStep25('T1-F', 'T1-F: degree', async () => {
        try {
          // degree_centrality.get() has no label filter â€” must scope via subgraph collection.
          // Collect Person+KNOWS subgraph first, then run algorithm only on those nodes/rels.
          // Source: graph.com/docs/advanced-algorithms/available-algorithms/degree_centrality
          await mageWrite(`
            MATCH (p:Person)-[r:KNOWS]-(q:Person)
            WITH COLLECT(DISTINCT p) + COLLECT(DISTINCT q) AS nodes, COLLECT(DISTINCT r) AS rels
            CALL degree_centrality.get_subgraph(nodes, rels, "undirected") YIELD node, degree
            WHERE 'Person' IN labels(node)
            SET node.degreeCentrality = degree
            RETURN count(*) AS n`);
        } catch (e1: any) {
          const notFound = e1?.message?.toLowerCase().includes('procedure') || e1?.message?.toLowerCase().includes('unknown');
          if (notFound) {
            // Fallback: count KNOWS edges only (social degree, not all relationship types)
            await mageWrite(
              `MATCH (p:Person)
               OPTIONAL MATCH (p)-[r:KNOWS]-()
               WITH p, count(r) AS deg
               SET p.degreeCentrality = toFloat(deg)
               RETURN count(*) AS n`
            );
          } else { throw e1; }
        }
        console.log('  âœ“ T1-F: degreeCentrality written');
      });
    }
    // Restore server-side query timeout to 600s (default) after MAGE block.
    // query.timeout is persistent â€” must always restore explicitly.
    // Source: graph.com/docs/database-management/configuration (query.timeout: persistent=yes)
    if (mg?.rawWrite) {
      try { await mg.rawWrite('SET DATABASE SETTING "query.timeout" TO "600"'); } catch { /* non-fatal */ }
    }
    // Restore storage.access_timeout_sec to 30s after T1 MAGE block.
    // T1 pre-flight raised it to 300s. Leaving 300s active causes quality-scorer
    // sequential writes to wait up to 5min per contact when HBO background writes
    // hold the storage lock momentarily. 30s is enough — HBO writes < 1s.
    if (mg?.rawWrite) {
      try {
        await mg.rawWrite("SET DATABASE SETTING 'storage.access_timeout_sec' TO '30'");
        console.log('  [T1 post-flight] storage.access_timeout_sec reset to 30s');
      } catch { /* non-fatal */ }
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 1.5 â€” KNOWS edge temporal features
    // Ported from scripts/run-backfill.ts Phase 3 Tier 0 temporalFeatures step.
    // Writes k.avgIntervalDays, dormancyDays, peakHour, weekdayRatio, totalMessages.
    // These feed comms_style signal and relationship strength scoring.
    //
    // BUG FIX: Previously queried via (me)-[:KNOWS]->(p) â€” this silently produces
    // 0 contacts when T0-PRE fails (no KNOWS edges from selfId). T1.5 then logs
    // nothing and leaves all KNOWS temporal fields null.
    // Fix: query contacts directly from all Person nodes that have Episodes,
    // then write to the KNOWS edge if it exists (OPTIONAL pattern).
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    if (mg?.rawWrite) {
      try {
        // â”€â”€ T1.5-PRE: Normalize KNOWS.temporalUpdatedAt ZonedDateTime â†’ LocalDateTime string â”€â”€
        // Prior code paths wrote temporalUpdatedAt as a ZonedDateTime (via datetime() or
        // localdatetime() on a build that stored zone info). The contact-selection query
        // below compares k2.temporalUpdatedAt >= localdatetime($cutoff) â€” Graph throws
        //   "Can't compare value of type zoned_date_time to value of type string"
        // when the stored value is a ZonedDateTime and the RHS is a LocalDateTime.
        // Fix: coerce all KNOWS.temporalUpdatedAt to plain YYYY-MM-DDThh:mm:ss strings.
        // Identical pattern to T0-C-PRE for Person.keyFactsAttemptedAt.
        // Source: graph.com/docs/fundamentals/data-types#localdatetime
        //   LocalDateTime comparison requires both sides to be the same type.
        // Idempotent: strings that are already plain ISO (no 'Z', '+', '[') are unchanged.
        await mg.rawWrite(
          `MATCH ()-[k:KNOWS]->()
           WHERE k.temporalUpdatedAt IS NOT NULL
           WITH k,
                toString(k.temporalUpdatedAt) AS rawStr
           WITH k, rawStr,
                split(split(split(rawStr, '[')[0], '.')[0], '+')[0] AS normalized
           WHERE normalized <> rawStr OR rawStr CONTAINS 'Z'
           SET k.temporalUpdatedAt = replace(normalized, 'Z', '')
           RETURN count(k) AS migrated`
        );

        // Strip milliseconds AND timezone offset for localdatetime() compatibility.
        // localdatetime() accepts YYYY-MM-DDThh:mm:ss only â€” no 'Z', no '+HH:MM'.
        // datetime() with 'Z' suffix produces ZonedDateTime; comparing ZonedDateTime
        // against the LocalDateTime stored in k2.temporalUpdatedAt throws type error.
        // Source: graph.com/docs/fundamentals/data-types#localdatetime
        //   "LocalDateTime is a point in time without timezone information."
        // Source: graph.com/docs/querying/functions#datetime-functions
        //   localdatetime() accepts string without timezone designator only.
        const cutoff1d = new Date(Date.now() - 86400000).toISOString().slice(0, 19);
        const { rawRead: _rr2 } = require('./lib/graph/graph-transport.js') as any;
        // Get all contacts who have episodes with stale/missing temporal features.
        // Does NOT require KNOWS edges â€” decoupled from T0-PRE/T0-B success.
        // T1.5 contact selection: find contacts with â‰¥2 episodes whose KNOWS edge
        // does NOT have a fresh temporalUpdatedAt (i.e. needs recomputation).
        // Graph does not support WHERE inside NOT EXISTS { pattern WHERE ... }.
        // Fix: use OPTIONAL MATCH + IS NULL pattern instead.
        const contactsForTemporal = await _rr2(
          `MATCH (p:Person)-[:AUTHORED]->(e:Episode)
           WHERE e.receivedAt IS NOT NULL AND p.isSelf IS NULL
           WITH p, count(e) AS epCount
           WHERE epCount >= 2
           OPTIONAL MATCH (me2:Person {id: $selfId})-[k2:KNOWS]->(p)
           WHERE k2.temporalUpdatedAt IS NOT NULL
              AND toString(k2.temporalUpdatedAt) >= $cutoff
           WITH p, k2
           WHERE k2 IS NULL
           WITH p.id AS pid,
                size([(me3:Person {id: $selfId})-[:KNOWS]->(p) | 1]) > 0 AS hasKnows
           RETURN pid, hasKnows`,
          { selfId: selfId ?? '', cutoff: cutoff1d }
        );
        if (!contactsForTemporal || contactsForTemporal.length === 0) {
          console.log('  â­ T1.5: no contacts with â‰¥2 episodes found â€” skipping temporal features');
        } else {
          // Batch episode fetch: one query for ALL contacts instead of 1 query per contact.
          // Source: graph.com/docs/data-migration/best-practices
          //   "UNWIND batching in a single transaction is the fastest" â€” same applies to reads.
          // Previously: 1000 contacts Ã— 1 rawRead = 1000 serial Bolt round-trips.
          // Now: 1 rawRead fetching all episodes, grouped by personId in JS.
          const allPids = contactsForTemporal.map((r: any) => r.pid as string);
          const allEpRows = await _rr2(
            `MATCH (p:Person)-[:AUTHORED]->(e:Episode)
             WHERE p.id IN $pids AND e.receivedAt IS NOT NULL
             RETURN p.id AS pid, toString(e.receivedAt) AS ts
             ORDER BY p.id ASC, toString(e.receivedAt) DESC`,
            { pids: allPids }
          );

          // Group by pid in JS
          const epsByPid = new Map<string, string[]>();
          for (const r of allEpRows as any[]) {
            if (!epsByPid.has(r.pid)) epsByPid.set(r.pid, []);
            const list = epsByPid.get(r.pid)!;
            list.push(String(r.ts));
          }

          // Compute temporal stats per contact in JS
          const knowsUpdates: any[] = [];
          const personUpdates: any[] = [];
          let temporalUpdated = 0;

          for (const row of contactsForTemporal) {
            try {
              // ZonedDateTime stringifies as "...+00:00[UTC]" — strip the bracketed
              // zone or new Date() yields NaN and every contact gets skipped.
              const tsList = (epsByPid.get(row.pid) || [])
                .map((ts: string) => new Date(ts.replace(/\[[^\]]*\]$/, '')).getTime())
                .filter((t: number) => !isNaN(t));
              if (tsList.length < 2) continue;
              const gaps = tsList.slice(0, -1).map((t: number, i: number) => (t - tsList[i + 1]) / 86400000);
              const avgGap = gaps.length > 0 ? gaps.reduce((a: number, b: number) => a + b, 0) / gaps.length : 0;
              if (isNaN(avgGap) || isNaN(tsList[0])) continue;
              const dormancy = (Date.now() - tsList[0]) / 86400000;
              const hourCounts = new Array(24).fill(0);
              tsList.forEach((t: number) => hourCounts[new Date(t).getHours()]++);
              const peakHour = hourCounts.indexOf(Math.max(...hourCounts));
              const weekdays = tsList.filter((t: number) => { const d = new Date(t).getDay(); return d > 0 && d < 6; }).length;
              const weekdayRatio = Math.round((weekdays / tsList.length) * 100) / 100;
              const stats = {
                pid: row.pid,
                avgGap: Math.round(avgGap * 10) / 10,
                dormancy: Math.round(dormancy),
                peakHour,
                weekdayRatio,
                total: tsList.length,
              };
              personUpdates.push(stats);
              if (row.hasKnows) knowsUpdates.push(stats);
              temporalUpdated++;
            } catch { /* skip individual contact */ }
          }

          // Write all Person node updates in one UNWIND batch
          // Source: graph.com/docs/data-migration/best-practices â€” "UNWIND batch = fastest"
          if (personUpdates.length > 0) {
            const T15_CHUNK = 500;
            for (let i = 0; i < personUpdates.length; i += T15_CHUNK) {
              const chunk = personUpdates.slice(i, i + T15_CHUNK);
              await mg.rawWrite(
                `UNWIND $items AS item
                 MATCH (p:Person {id: item.pid})
                 SET p.avgIntervalDays = item.avgGap,
                     p.dormancyDays    = item.dormancy,
                     p.peakHour        = item.peakHour,
                     p.weekdayRatio    = item.weekdayRatio,
                     p.totalMessages   = item.total
                 RETURN count(p) AS updated`,
                { items: chunk }
              );
            }
          }

          // Write all KNOWS edge updates in one UNWIND batch
          if (knowsUpdates.length > 0 && selfId) {
            const T15_CHUNK = 500;
            for (let i = 0; i < knowsUpdates.length; i += T15_CHUNK) {
              const chunk = knowsUpdates.slice(i, i + T15_CHUNK);
              await mg.rawWrite(
                `UNWIND $items AS item
                 MATCH (me:Person {id: $selfId})-[k:KNOWS]->(p:Person {id: item.pid})
                 SET k.avgIntervalDays    = item.avgGap,
                     k.dormancyDays       = item.dormancy,
                     k.peakHour           = item.peakHour,
                     k.weekdayRatio       = item.weekdayRatio,
                     k.totalMessages      = item.total,
                     k.temporalUpdatedAt  = localdatetime()
                 RETURN count(k) AS updated`,
                { selfId, items: chunk }
              );
            }
          }

          console.log(`  âœ“ T1.5: temporalFeatures written for ${temporalUpdated}/${contactsForTemporal.length} contacts`);
          _forensicWrite({ event: 'step_ok', id: 'T1.5', counters: { matched: contactsForTemporal.length, written: temporalUpdated } });
        }
      } catch (e: any) { console.warn(`  âš  T1.5: temporalFeatures failed (non-fatal): ${e?.message?.slice(0,80)}`); }
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 1.6 â€” Veto fields batch
    // Ported from scripts/run-backfill.ts Phase 3 Tier 0 vetoFieldsBatch step.
    // Writes p.recentInboundCount, p.avgWeeklyInbound, p.lastOutboundTo.
    // frequency-acceleration signal reads recentInboundCount + avgWeeklyInbound.
    // Requires: Episode nodes (T0-A)
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    if (mg?.rawWrite && selfId) {
      try {
        // Strip milliseconds â€” Graph datetime() rejects sub-second components in string form.
        const cutoff7d = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 19) + 'Z';
        const cutoff90d = new Date(Date.now() - 90 * 86400000).toISOString().slice(0, 19) + 'Z';
        // Use datetime() comparison, not string comparison.
        // toString(ZonedDateTime) produces "2026-01-15T10:00:00+05:30[Asia/Kolkata]"
        // which compares as less-than "2026-01-15T..." because "+" (43) < "0" (48) in ASCII.
        // String comparison of mixed-timezone ISO strings silently excludes non-UTC episodes.
        // datetime() normalises all values to UTC before comparing.
        // Source: graph.com/docs/querying/functions#temporal-functions
        await mg.rawWrite(
          `MATCH (me:Person {id: $selfId})-[:KNOWS]->(p:Person)
           OPTIONAL MATCH (p)-[:AUTHORED]->(e7:Episode)
              WHERE e7.direction = 'inbound' AND e7.receivedAt >= datetime($cutoff7d)
           OPTIONAL MATCH (p)-[:AUTHORED]->(e90:Episode)
              WHERE e90.direction = 'inbound' AND e90.receivedAt >= datetime($cutoff90d)
          WITH p,
            count(DISTINCT e7)  AS inbound7d,
            count(DISTINCT e90) AS inbound90d
          SET p.recentInboundCount = toInteger(inbound7d),
              p.avgWeeklyInbound   = round(toFloat(inbound90d) / 13.0 * 100) / 100
          RETURN count(p) AS updated`,
          { selfId, cutoff7d, cutoff90d }
        );
        console.log('  âœ“ T1.6: recentInboundCount + avgWeeklyInbound written');
      } catch (e: any) { console.warn(`  âš  T1.6: vetoFieldsBatch failed (non-fatal): ${e?.message?.slice(0,80)}`); }
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 2 â€” Metadata signals (MUST run before FAVEE)
    // computeEmailMetadataSignals() writes k.metadataSignals to KNOWS edges.
    // The FAVEE bulk query filters: WHERE k.metadataSignals IS NOT NULL
    // Without this step, FAVEE finds 0 contacts and writes nothing.
    // Requires: Episode nodes (T0-A), self-KNOWS edges (T0-B)
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    try {
      const { computeEmailMetadataSignals } = await import('./lib/triage-core/mental-model/metadata-signals.ts');
      // Remove limit â€” process all contacts. Previously capped at 2000, leaving 80%+ unprocessed
      // on large inboxes. The function has internal timeout handling per contact.
      const metaResult = await computeEmailMetadataSignals({ mePersonId: selfId || undefined });
      console.log(`  âœ“ T2: computeEmailMetadataSignals â†’ ${metaResult.updated} contacts, ${metaResult.errors} errors (${Math.round(metaResult.elapsed / 1000)}s)`);
    } catch (e: any) {
      console.warn(`  âš  T2: computeEmailMetadataSignals failed (non-fatal): ${e?.message?.slice(0,100)}`);
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 3 â€” enrichAll() canonical orchestrator
    // Runs in order: FAVEE â†’ Dunbar â†’ relationshipStrength â†’ qualityProfiles
    //   â†’ commsStyle â†’ trajectoryDetect â†’ key-facts (Qwen3 LLM) â†’ goals-sync
    //   â†’ goal-embeddings â†’ person-embeddings â†’ FAVEESnapshots
    //   â†’ strengthSnapshots â†’ VIP detection
    // Requires: metadataSignals (T2) to be non-null on KNOWS edges
    //
    // skipLLM and skipEmbeddings REMOVED â€” key-facts now runs via Qwen3 (local,
    // always available), embeddings via MAGE (gracefully skipped if proc missing).
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    try {
      const { enrichAll } = await import('./lib/triage-core/mental-model/enrich-all.ts');
      let report = await enrichAll();
      // If the DB was wedged (daemon DDL storm, MAGE step holding storage),
      // every step fails fast with driver timeouts and the run reports zeros.
      // One retry after the DB has had time to recover salvages the whole tier.
      const driverErrs = report.errors.filter((e: string) => /driver failed|timeout|ECONNREFUSED/i.test(e)).length;
      if (driverErrs >= 2) {
        console.warn(`  T3: enrichAll hit ${driverErrs} driver failures (DB likely wedged) — retrying once in 60s...`);
        await new Promise(r => setTimeout(r, 60_000));
        report = await enrichAll();
      }
      console.log(`  âœ“ T3: enrichAll complete in ${Math.round((Date.now() - enrichStart) / 1000)}s:`);
      sendIPC({ type: 'step', ts: Date.now(), step: 'T3', state: 'done' });
      console.log(`    FAVEE: ${report.faveeScored} | Dunbar: ${report.dunbarClassified} | Strength: ${report.strengthPrecomputed ?? 0}`);
      console.log(`    QualityProfiles: ${report.qualityScored ?? 0} | Trajectories: ${report.trajectoriesComputed ?? 0}`);
      console.log(`    KeyFacts: ${report.keyFactsExtracted ?? 0} | Snapshots: ${report.strengthSnapshots} | VIPs: ${report.vipsDetected ?? 0}`);
      _forensicWrite({ event: 'step_ok', id: 'T3-enrichAll', counters: report });
      if (report.errors.length > 0) console.log(`    âš  ${report.errors.length} error(s): ${report.errors.slice(0,3).join('; ')}`);
    } catch (e: any) {
      console.warn(`  âš  T3: enrichAll failed â€” signals will use defaults: ${e?.message?.slice(0,100)}`);
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 3.8 â€” Structural ML enrichment (node2vec, k-means, episode embeddings,
    //             node-similarity)
    // These were in runPostIngestionEnrichment() but never called from backfill.
    // Added here: node2vec structural embeddings â†’ k-means contact segments â†’
    //   node-similarity SIMILAR_TO edges â†’ episode text embeddings.
    // All steps are non-fatal â€” errors are logged and backfill continues.
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    try {
      const { runNode2Vec, runKMeansClustering, runNodeSimilarity, embedEmailEpisodes } =
        await import('./lib/triage-core/graph/enrichment.ts');

      // T3.8-A: Node2Vec structural embeddings (Person.node2vec_embedding, 128-dim)
      // Shares the SKIP_MAGE_CLUSTERING kill-switch with T1-D/T1-E: node2vec is a
      // MAGE procedure observed to SIGSEGV Graph 3.11 at T3.8 start on two
      // consecutive runs (2026-07-07/08 journalctl), taking down every later step
      // in the ~20s systemd restart window.
      if (process.env.SKIP_MAGE_CLUSTERING === '1') {
        console.log('  T3.8-A/B: node2vec + k-means skipped (SKIP_MAGE_CLUSTERING=1)');
        _forensicWrite({ event: 'step_skip', id: 'T3.8-A/B', reason: 'SKIP_MAGE_CLUSTERING=1' });
      } else {
      try {
        const _t38a = Date.now();
        const n2vCount = await Promise.race([runNode2Vec(), new Promise<number>((_, rej) => setTimeout(() => rej(new Error('timeout')), 600_000))]);
        _forensicWrite({ event: 'step_ok', id: 'T3.8-A', durationMs: Date.now() - _t38a, counters: { written: n2vCount } });
        console.log(`  âœ“ T3.8-A: node2vec â†’ ${n2vCount} Person nodes embedded`);
      } catch (e: any) { _forensicWrite({ event: 'step_fail', id: 'T3.8-A', error: String(e?.message || '').slice(0, 160) }); console.warn(`  T3.8-A: node2vec failed (non-fatal): ${e?.message?.slice(0,80)}`); }

      // T3.8-B: K-means contact segmentation (Person.contactSegment)
      // Requires node2vec embeddings from T3.8-A
      try {
        const _t38b = Date.now();
        const kCount = await Promise.race([runKMeansClustering(), new Promise<number>((_, rej) => setTimeout(() => rej(new Error('timeout')), 300_000))]);
        _forensicWrite({ event: 'step_ok', id: 'T3.8-B', durationMs: Date.now() - _t38b, counters: { written: kCount } });
        console.log(`  âœ“ T3.8-B: k-means â†’ ${kCount} contact clusters`);
      } catch (e: any) { _forensicWrite({ event: 'step_fail', id: 'T3.8-B', error: String(e?.message || '').slice(0, 160) }); console.warn(`  T3.8-B: k-means failed (non-fatal): ${e?.message?.slice(0,80)}`); }

      }

      // T3.8-C: Episode text embeddings (Episode.embedding, 768-dim via all-mpnet-base-v2)
      try {
        // Episode embedding covers 5k-50k episodes on a 30-day inbox; 60s guaranteed timeout-death.
        const _t38c = Date.now();
        const epCount = await Promise.race([embedEmailEpisodes(), new Promise<number>((_, rej) => setTimeout(() => rej(new Error('timeout')), 3_600_000))]);
        _forensicWrite({ event: 'step_ok', id: 'T3.8-C', durationMs: Date.now() - _t38c, counters: { written: epCount } });
        console.log(`  âœ“ T3.8-C: episode embeddings â†’ ${epCount} episodes embedded`);
      } catch (e: any) { _forensicWrite({ event: 'step_fail', id: 'T3.8-C', error: String(e?.message || '').slice(0, 160) }); console.warn(`  T3.8-C: episode embeddings failed (non-fatal): ${e?.message?.slice(0,80)}`); }

      // T3.8-D: Node similarity â€” creates SIMILAR_TO edges between structurally equivalent contacts
      // Threshold 0.5, limit 5000 pairs
      try {
        const _t38d = Date.now();
        const simCount = await Promise.race([runNodeSimilarity(), new Promise<number>((_, rej) => setTimeout(() => rej(new Error('timeout')), 300_000))]);
        _forensicWrite({ event: 'step_ok', id: 'T3.8-D', durationMs: Date.now() - _t38d, counters: { written: simCount } });
         console.log(`  âœ“ T3.8-D: node-similarity â†’ ${simCount} SIMILAR_TO edges`);
       } catch (e: any) { _forensicWrite({ event: 'step_fail', id: 'T3.8-D', error: String(e?.message || '').slice(0, 160) }); console.warn(`  T3.8-D: node-similarity failed (non-fatal): ${e?.message?.slice(0,80)}`); }

    } catch (importErr: any) {
      console.warn(`  âš  T3.8: structural ML enrichment import failed (non-fatal): ${importErr?.message?.slice(0,80)}`);
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 3.9 â€” Lightweight graph ML (no PyTorch/DGL)
    // link_prediction_lite: Adamic-Adar + Resource Allocation + temporal score
    // temporal_graph_lite: next-contact likelihood + overdue detection
    // Writes PREDICTED_KNOWS edges + Person.temporalOverdueScore
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    try {
      const mageRw = (_require('./lib/graph/graph-transport.js') as any)?.autoCommit;
      if (mageRw) {
        // T3.9-A: Link prediction â€” top-20 missing KNOWS edges by Adamic-Adar
        try {
          const linkPreds = await mageRw(`
            CALL link_prediction_lite.adamic_adar(20)
            YIELD node1, node2, score
            WHERE score > 0.05
            MERGE (node1)-[r:PREDICTED_KNOWS]->(node2)
            ON CREATE SET r.score = score, r.method = 'adamic_adar', r.predictedAt = localdatetime()
            ON MATCH  SET r.score = score
            RETURN count(*) AS n`);
          const n = linkPreds?.[0]?.n?.toNumber?.() ?? Number(linkPreds?.[0]?.n ?? 0);
          console.log(`  âœ“ T3.9-A: link prediction (Adamic-Adar) â†’ ${n} PREDICTED_KNOWS edges`);
        } catch (e: any) { console.warn(`  âš  T3.9-A: link prediction failed (non-fatal): ${e?.message?.slice(0,80)}`); }

        // T3.9-B: Temporal scoring â€” contacts likely to reach out in next 7 days
        try {
          const temporal = await mageRw(`
            CALL temporal_graph_lite.next_contact_score(30, 30.0)
            YIELD person, score
            SET person.temporalContactScore = score
            RETURN count(*) AS n`);
          const n = temporal?.[0]?.n?.toNumber?.() ?? Number(temporal?.[0]?.n ?? 0);
          console.log(`  âœ“ T3.9-B: temporal next-contact score â†’ ${n} contacts scored`);
        } catch (e: any) { console.warn(`  âš  T3.9-B: temporal scoring failed (non-fatal): ${e?.message?.slice(0,80)}`); }

        // T3.9-C: Overdue contacts â€” gone silent beyond normal cadence
        try {
          const overdue = await mageRw(`
            CALL temporal_graph_lite.overdue_contacts(2.0)
            YIELD person, overdue_score
            SET person.temporalOverdueScore = overdue_score
            RETURN count(*) AS n`);
          const n = overdue?.[0]?.n?.toNumber?.() ?? Number(overdue?.[0]?.n ?? 0);
          console.log(`  âœ“ T3.9-C: overdue contact detection â†’ ${n} overdue contacts flagged`);
        } catch (e: any) { console.warn(`  âš  T3.9-C: overdue detection failed (non-fatal): ${e?.message?.slice(0,80)}`); }
      }
    } catch (t39err: any) {
      console.warn(`  âš  T3.9: lightweight graph ML failed (non-fatal): ${t39err?.message?.slice(0,80)}`);
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 3.5 â€” LLM-powered role and conversation enrichment
    // Requires: T3 (enrichAll) â€” FAVEE + Dunbar + metadataSignals on KNOWS edges
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€

    // T3.5-A: Signal-based role backfill (Pass 1 â€” no LLM, pure pattern matching)
    // Infers roles for intimate/close contacts from FAVEE + metadata signals.
    // Skip guard: only processes contacts without human-verified roles.
    try {
      const { backfillRoles } = await import('./lib/triage-core/mental-model/backfill-roles.ts');
      const rolesResult = await backfillRoles({ mePersonId: selfId || undefined });
      console.log(`  âœ“ T3.5-A: backfillRoles (Pass 1 signal-based) â†’ ${rolesResult.updated} updated, ${rolesResult.skipped} skipped`);
    } catch (e: any) {
      console.warn(`  âš  T3.5-A: backfillRoles failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }

    // T3.5-B: LLM role inference (Pass 2) â€” for contacts stuck with default 'friend' role
    // Target: intimate/close + totalMessages > 20 + llmProcessedAt IS NULL
    // Writes: k.roles, k.roleSource='llm_inference', k.llmProcessedAt
    try {
      const { inferRolesWithLLM } = await import('./lib/triage-core/mental-model/backfill-roles.ts');
      const llmRolesResult = await inferRolesWithLLM({ mePersonId: selfId || undefined, dryRun: false });
      console.log(`  âœ“ T3.5-B: inferRolesWithLLM (Pass 2 LLM) â†’ ${llmRolesResult.succeeded} updated, ${llmRolesResult.zeroRoles} no-role, ${llmRolesResult.failed} failed`);
    } catch (e: any) {
      console.warn(`  âš  T3.5-B: inferRolesWithLLM failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }

    // T3.5-C: Conversation-level fact extraction
    // Groups Episodes into 4h temporal windows, extracts 3-10 facts per window.
    // Skip guard: contacts with >= 5 existing conversation_extractor facts are skipped.
    // Writes: KeyFact nodes with source='conversation_extractor', Person.conversationFactsUpdatedAt
    try {
      const { extractAllConversationFacts } = await import('./lib/triage-core/mental-model/conversation-extractor.ts');
      const convResult = await extractAllConversationFacts(200, 100); // raised from 50 contacts â†’ 200
      console.log(`  âœ“ T3.5-C: extractAllConversationFacts â†’ ${convResult.factsExtracted} facts from ${convResult.conversationCount} conversations`);
    } catch (e: any) {
      console.warn(`  âš  T3.5-C: extractAllConversationFacts failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }

    // T3.5-D: LLM Role + FAVEE V2 inference (Qwen3 â†’ Ollama â†’ cloud)
    // Reads Graph Episodes directly (refactored from file-on-disk contact-samples.json).
    // Classifies 24-item relationship role enum + FAVEE dimensional scores per contact.
    // Skip guard: contacts with llmRoleV2 IS NOT NULL && llmConfidence >= 0.25 are skipped.
    // Writes: KNOWS.llmRoleV2, llmFaveeV2, llmConfidence, llmTrajectory, llmEvidence, llmPossibleRoles
    // Source: graph.com/docs/querying/clauses/merge â€” idempotent MERGE pattern for skip guard
    // Source: node-llama-cpp.withcat.ai/guide/chat-session â€” noGrammar=true for free-form JSON output
    try {
      const { runLLMRoleFaveeV2 } = await import('./lib/triage-core/mental-model/llm-role-favee-v2.ts');
      const roleFaveeResult = await runLLMRoleFaveeV2({ mePersonId: selfId || undefined, limit: parseInt(process.env.T35_ROLE_FAVEE_LIMIT ?? '5000', 10) });
      console.log(`  âœ“ T3.5-D: runLLMRoleFaveeV2 â†’ ${roleFaveeResult.succeeded} succeeded, ${roleFaveeResult.skipped} skipped, ${roleFaveeResult.failed} failed`);
    } catch (e: any) {
      console.warn(`  âš  T3.5-D: runLLMRoleFaveeV2 failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 4 â€” Post-enrichAll snapshots and velocity
    // Must run AFTER enrichAll has populated KNOWS.compositeStrength
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€

    // T4-A: prevCompositeStrength snapshot â€” trajectory_signal delta baseline
    if (mg?.rawWrite) {
      try {
        await mg.rawWrite('MATCH ()-[k:KNOWS]->() WHERE k.compositeStrength IS NOT NULL SET k.prevCompositeStrength = k.compositeStrength');
        console.log('  âœ“ T4-A: KNOWS.prevCompositeStrength snapshotted');
      } catch (e: any) { console.warn(`  âš  T4-A: prevCompositeStrength snapshot failed (non-fatal): ${e?.message?.slice(0,60)}`); }
    }

    // T4-B: computeTrajectories() â€” trajectory_momentum (p.trajectoryVelocity)
    // enrichAll's detectTrajectories() requires 2+ FAVEESnapshots (needs 2+ weekly runs).
    // computeTrajectories() from strength-tracker uses compositeStrength deltas instead â€”
    // works on first run.
    try {
      const { computeTrajectories } = await import('./lib/triage-core/mental-model/strength-tracker.ts');
      const n = await computeTrajectories();
      console.log(`  âœ“ T4-B: trajectoryVelocity computed for ${n} contacts`);
    } catch (e: any) { console.warn(`  âš  T4-B: computeTrajectories failed (non-fatal): ${e?.message?.slice(0,60)}`); }

    // T4-C: computeAllStyles() â€” comms_style signal (avgMessageLength, emojiRate, formalityScore)
    // Run separately after enrichAll to catch contacts without KNOWS edges.
    try {
      const { computeAllStyles } = await import('./lib/triage-core/mental-model/comms-style-computer.ts');
      const r = await computeAllStyles();
      console.log(`  âœ“ T4-C: commsStyle computed for ${r.updated} contacts`);
    } catch (e: any) { console.warn(`  âš  T4-C: computeAllStyles failed (non-fatal): ${e?.message?.slice(0,60)}`); }

    // T4-D: resilience-monitor â€” relationship_persistence + relationship_health
    // Writes p.resilienceScore, p.resilienceLevel. Requires leidenCommunityId (T1-E).
    // Ported from scripts/run-backfill.ts Phase 4.
    try {
      const _require = require;
      const resilienceMod = (() => { try { return _require('./lib/triage-core/mental-model/resilience-monitor.js'); } catch { return null; } })();
      if (resilienceMod && typeof resilienceMod.computeResilience === 'function') {
        const results: Array<{personId: string; resilienceScore: number; resilienceLevel: string}> = await resilienceMod.computeResilience(9999);
        const validResults = (results || []).filter((r: any) => r?.personId && r?.resilienceScore != null);
        if (validResults.length > 0 && mg?.rawWrite) {
          // Batch the resilienceScore writes using UNWIND instead of one write per person.
          // Previously: validResults.length serial rawWrite calls (up to 9999 contacts).
          // Now: ceil(N/500) UNWIND batch writes.
          // Source: graph.com/docs/data-migration/best-practices â€” UNWIND batch is fastest.
          const T4D_CHUNK = 500;
          let written = 0;
          for (let i = 0; i < validResults.length; i += T4D_CHUNK) {
            const chunk = validResults.slice(i, i + T4D_CHUNK);
            try {
              await mg.rawWrite(
                `UNWIND $items AS item
                 MATCH (p:Person {id: item.pid})
                 SET p.resilienceScore = item.score,
                     p.resilienceLevel = item.level,
                     p.resilienceUpdatedAt = localdatetime()
                 RETURN count(p) AS updated`,
                { items: chunk.map((r: any) => ({ pid: r.personId, score: r.resilienceScore, level: r.resilienceLevel || 'UNKNOWN' })) }
              );
              written += chunk.length;
            } catch { /* skip chunk â€” non-fatal */ }
          }
          console.log(`  âœ“ T4-D: resilienceScore written for ${written} contacts`);
        }
      } else {
        // resilience-monitor not available as compiled JS â€” try TS import
        const { computeResilience } = await import('./lib/triage-core/mental-model/resilience-monitor.ts').catch(() => ({ computeResilience: null })) as any;
        if (typeof computeResilience === 'function') {
          const results = await computeResilience(9999);
          console.log(`  âœ“ T4-D: resilienceScore computed for ${(results||[]).length} contacts`);
        } else {
          // Neither .js nor .ts module available â€” skip gracefully with explicit log.
          // resilienceScore and resilienceLevel will remain null for all contacts.
          // To fix: compile resilience-monitor.ts to .js or ensure tsx resolves it.
          console.log('  â­ T4-D: resilience-monitor module not available (neither .js nor .ts found) â€” resilienceScore not written');
        }
      }
    } catch (e: any) { console.warn(`  âš  T4-D: resilience-monitor failed (non-fatal): ${e?.message?.slice(0,80)}`); }

    // T4-E: linkOrphanedEpisodes â€” ensure all Episode nodes have AUTHORED edges
    // Some Episodes may be created without AUTHORED edges (e.g. if sender resolution failed).
    // Ported from scripts/run-backfill.ts Phase 3 Tier 0 + Phase 5.5.
    try {
      const { linkOrphanedEpisodes } = await import('./lib/triage-core/mental-model/link-orphaned-episodes.ts').catch(() => ({ linkOrphanedEpisodes: null })) as any;
      if (typeof linkOrphanedEpisodes === 'function') {
        const result = await linkOrphanedEpisodes({ limit: 9999 });
        if ((result?.linked ?? 0) > 0) console.log(`  âœ“ T4-E: ${result.linked} orphaned episodes linked`);
      }
    } catch (e: any) { console.warn(`  âš  T4-E: linkOrphanedEpisodes failed (non-fatal): ${e?.message?.slice(0,80)}`); }

    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    // TIER 4.5 â€” Post-T4 cross-contact consolidation and summary generation
    // Requires: KeyFact nodes with embeddings (T3 key-facts + T3.5-C conv-extractor)
    // â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€

    // T4.5-A: KeyFact consolidation â€” merge cross-contact KeyFact pairs (cosine sim > 0.85)
    // into SemanticFact nodes. Requires MAGE vector_search procedure + embeddings.
    // No skip guard â€” always re-runs (creates new SemanticFact nodes, does not overwrite).
    try {
      const { consolidateRelatedFacts } = await import('./lib/triage-core/mental-model/keyfact-consolidation.ts');
      const consolidationResult = await consolidateRelatedFacts();
      console.log(`  âœ“ T4.5-A: consolidateRelatedFacts â†’ ${consolidationResult.merged} merged, ${consolidationResult.skipped} skipped`);
    } catch (e: any) {
      console.warn(`  âš  T4.5-A: consolidateRelatedFacts failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }

    // T4.5-B: Summary generation — regenerate Person.summary for stale or missing summaries
    // Uses shouldRegenerateSummary() TTL (7-day) + key-facts freshness gate.
    // Writes: Person.summary, Person.summaryUpdatedAt
    // Note: summary-generator.ts auto-wires getTriageLLM() at module load.
    // Resilience: if Graph crashes mid-run (ECONNREFUSED), wait 60s for restart
    // then re-fetch personRows and resume (already-written contacts skip via TTL check).
    for (let _t45bAttempt = 0; _t45bAttempt < 3; _t45bAttempt++) {
    try {
      const { assembleMentalModel } = await import('./lib/triage-core/mental-model/model-assembler.ts');
      const { shouldRegenerateSummary, generateSummary, persistSummary } = await import('./lib/triage-core/mental-model/summary-generator.ts');
      const { rawRead: rawReadMg } = require('./lib/graph/graph-transport.js');
      // Sort: contacts with no summary first (guaranteed generation), then stale ones.
      // This ensures newly-added contacts get summaries before the much larger
      // set of contacts whose summaries need regeneration due to TTL/fact changes.
      let personRows: Array<{ personId: string }> = await rawReadMg(
        `MATCH (me:Person {id: $selfId})-[:KNOWS]-(p:Person)
         WHERE p.id <> $selfId
         RETURN p.id AS personId,
                p.summary IS NULL AS needsSummary,
                p.summaryUpdatedAt AS updatedAt
         ORDER BY needsSummary DESC, p.summaryUpdatedAt ASC`,
        { selfId }
      );
      {
        const { filterCanary } = await import('./lib/triage-core/canary.ts');
        personRows = await filterCanary(personRows, (r) => r.personId);
      }
      let summariesGenerated = 0;
      let summariesSkipped = 0;
      // Process summaries with limited concurrency (4 at a time).
      // assembleMentalModel runs ~8 parallel graph queries per contact internally.
      // 4 concurrent contacts x 8 queries = 32 in-flight graph reads through the transport.
      const T45B_CONCURRENCY = 4;
      for (let i = 0; i < personRows.length; i += T45B_CONCURRENCY) {
        const batch = personRows.slice(i, i + T45B_CONCURRENCY);
        const results = await Promise.allSettled(
          batch.map(async ({ personId }) => {
            try {
              const model = await assembleMentalModel(personId);
              if (shouldRegenerateSummary(model)) {
                const summary = await generateSummary(model);
                await persistSummary(personId, summary);
                return 'generated';
              }
              return 'skipped';
            } catch {
              return 'skipped';
            }
          })
        );
        for (const r of results) {
          if (r.status === 'fulfilled' && r.value === 'generated') summariesGenerated++;
          else summariesSkipped++;
        }
      }
      console.log(`  \u2714 T4.5-B: summaries \u2192 ${summariesGenerated} generated, ${summariesSkipped} skipped`);
      break; // success - exit retry loop
    } catch (e: any) {
      const isConnErr = e?.message?.includes('ECONNREFUSED') || e?.message?.includes('Failed to connect');
      if (isConnErr && _t45bAttempt < 2) {
        console.warn(`  \u26a0 T4.5-B: Graph connection lost (attempt ${_t45bAttempt + 1}/3) - waiting 60s for restart...`);
        await new Promise(r => setTimeout(r, 60_000));
        continue; // retry
      }
      console.warn(`  \u26a0 T4.5-B: summary generation failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }
    } // end T4.5-B retry loop

    // T4.5-C: Situation detection â€” detect cross-contact patterns as Situations
    // Uses cursor-based scanning so only Episodes since last run are processed.
    // Writes: Situation nodes (state, priority, summary, userRole, urgency) + INVOLVED_IN edges.
    // Also writes to triage_situations SQL table via dual-write (SQL fallback for Graph-down users).
    // Source: graph.com/docs/querying/clauses/merge â€” idempotent MERGE on coreEntityId
    // Source: graph.com/docs/advanced-algorithms â€” entity co-occurrence pattern
    try {
      const { detectSituations } = await import('./lib/triage-core/mental-model/situation-detector.ts');
      const sitResult = await detectSituations();
      console.log(`  âœ“ T4.5-C: detectSituations â†’ ${sitResult.created} created, ${sitResult.updated} updated, ${sitResult.staled} staled`);
    } catch (e: any) {
      console.warn(`  âš  T4.5-C: detectSituations failed (non-fatal): ${e?.message?.slice(0, 100)}`);
    }

    console.log(`\n  Phase 2.5 total: ${Math.round((Date.now() - enrichStart) / 1000)}s`);
    sendIPC({ type: 'phase', ts: Date.now(), phase: '2.5', label: 'Enrichment', state: 'done', elapsed: Math.round((Date.now() - enrichStart) / 1000) });
    console.log('  Signal coverage: T0-PRE(self-unify) â†’ T0(graph) â†’ T1(MAGE) â†’ T1.5(temporal) â†’ T1.6(veto) â†’ T2(metadata) â†’ T3(FAVEE/Dunbar/quality) â†’ T3.5(roles/favee/conversation-facts) â†’ T4(snapshots/resilience) â†’ T4.5(consolidation/summaries/situations)');
  }

  if (!enrichmentOnly) { // Phases 3 + 4

  // ── Cost gate (advisory estimate + optional --max-cost hard cap) ─────────
  // Runs before Phase 3 (and under --dry-run, so cost can be previewed). The
  // abort-throw for --max-cost still fires under --dry-run.
  //
  // Email-count signal: Phase 3 triages the emails in the local Gmail index that
  // fall inside [since, until). Recompute that count directly from the index file
  // — the same real signal Phase 3 consumes. The estimate is advisory, so an
  // approximate count (e.g. stale/offline index) is acceptable. Falls back to 0
  // (→ $0 estimate) when the index is missing.
  let _costGateEmailCount = 0;
  try {
    if (existsSync(INDEX_30D_PATH)) {
      const _idx = [...iterateJsonArrayFile(INDEX_30D_PATH)];
      const _sinceMs = since.getTime();
      const _untilMs = until.getTime();
      _costGateEmailCount = _idx.filter((m: any) => {
        if (!m?.date) return false;
        const d = new Date(m.date);
        return !isNaN(d.getTime()) && d.getTime() >= _sinceMs && d.getTime() <= _untilMs;
      }).length;
    }
  } catch { /* non-fatal — advisory estimate falls back to 0 emails */ }
  costGate(_costGateEmailCount, { skipDrafts, maxCost, force });

  const triageItems = await phase3RunTriage({ account, since, until, limit, dryRun, offline, skipDrafts, resetPhase3 });

  // FIX-C01: Update triage-state.json watermark so next run-triage-now.ts starts
  // from the correct point instead of re-processing all backfilled emails.
  const TRIAGE_STATE_PATH = join(ELYNTIC_DATA_DIR, 'triage-state.json');
  try {
    const existingState = existsSync(TRIAGE_STATE_PATH)
      ? JSON.parse(readFileSync(TRIAGE_STATE_PATH, 'utf-8')) : {};
    writeFileSync(TRIAGE_STATE_PATH, JSON.stringify({
      ...existingState,
      lastSuccessAt: until.toISOString(),
      lastBackfillCompletedAt: new Date().toISOString(),
      lastBackfillUntil: until.toISOString(),
      source: 'backfill',
    }, null, 2));
    console.log('  âœ“ Watermark updated â†’ triage-state.json (lastSuccessAt:', until.toISOString(), ')');
  } catch (err) {
    console.warn('  âš  Could not update triage-state.json watermark:', (err as Error).message);
  }

  // â”€â”€ Phase 3b: Persist bodies â†’ Graph â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Bodies are fetched live in Phase 3 but Phase 2 only stored metadata.
  // Write them back so future queries, searches, and re-triage have the body.
  if (!dryRun) {
    await phase3bPersistBodies(triageItems);
  }

  // â”€â”€ Phase 4: Dashboard â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  await phase4GenerateDashboard(dryRun);

  } // end Phases 3+4 block



  // â”€â”€ Phase 5: Organization mapping â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  // Runs unconditionally (outside enrichmentOnly block) so enrichment-only runs
  // also pick up org mapping. Skipped via --skip-org.
  if (!skipOrg && !legacyGraphEnabled()) {
    // BACKFILL-GRAPH-SWEEP-1: Phase 5 infers Organizations from email domains
    // entirely in Cypher (Organization nodes, WORKS_AT edges) and has no
    // canonical table to write to. A call-site trace identified it as the last
    // remaining graph query on a graph-free run. It already guarded itself with
    // "if (!_mg) skip", so it degraded silently; it is skipped LOUDLY here
    // instead, before the require that opens the connection.
    console.log('\nPhase 5/5: Org mapping - SKIPPED (no graph engine)');
    console.log('  Organization inference and WORKS_AT edges are Cypher-only and have no');
    console.log('  canonical table. Nothing was written. Re-enable with ELYNTIC_BACKFILL_LEGACY_GRAPH=1.');
  } else if (!skipOrg) {
    // Pass dryRun through so Phase 5 can show projected counts without writing.
    await phase5OrgMapping({ selfId: process.env.ELYNTIC_SELF_ID || '', skipLLM: skipEnrichment, dryRun, limit });
  } else if (skipOrg) {
    console.log('\nPhase 5/5: Org mapping â€” skipped (--skip-org)');
  }

  // â”€â”€ Final Summary â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  console.log('\nâ•”â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•—');
  console.log('â•‘  Backfill Complete                                      â•‘');
  console.log('â•šâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•');

  const finalCheckpoint = loadCheckpoint(CHECKPOINT_PATH);
  if (finalCheckpoint) {
    if (finalCheckpoint.phase1MessagesCount !== undefined) {
      console.log(`Phase 1 â€” Gmail index: ${finalCheckpoint.phase1MessagesCount} messages (source: ${finalCheckpoint.source || 'unknown'})`);
    }
    if (finalCheckpoint.phase2EmailsCreated !== undefined) {
      console.log(`Phase 2 â€” Graph: ${finalCheckpoint.phase2EmailsCreated} emails, ${finalCheckpoint.phase2PersonsCreated} persons, ${finalCheckpoint.phase2EdgesCreated} edges`);
    }
    if (finalCheckpoint.phase3P0 !== undefined) {
      console.log(`Phase 3 â€” Triage: P0=${finalCheckpoint.phase3P0} P1=${finalCheckpoint.phase3P1} P2=${finalCheckpoint.phase3P2} P3=${finalCheckpoint.phase3P3}`);
      console.log(`Phase 3 â€” Drafts: ${finalCheckpoint.phase3DraftCount ?? 0} AI-generated replies`);
    }
  }

  // â”€â”€ Verify outputs â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
  console.log('\nOutput verification:');

  const briefingPath = join(TRIAGE_DIR, 'latest-briefing.json');
  if (existsSync(briefingPath)) {
    const briefing = JSON.parse(readFileSync(briefingPath, 'utf-8'));
    const generatedAt = briefing.generatedAt || 'unknown';
    const ageMs = Date.now() - new Date(generatedAt).getTime();
    const ageMin = Math.floor(ageMs / 60000);
    const draftCount = (briefing.draftItems || []).length;
    console.log(`  âœ“ latest-briefing.json`);
    console.log(`    generatedAt: ${generatedAt} (${ageMin}m ago)`);
    console.log(`    draftItems: ${draftCount}`);
    console.log(`    stats: P0=${briefing.stats?.p0Count ?? '?'} P1=${briefing.stats?.p1Count ?? '?'} P2=${briefing.stats?.p2Count ?? '?'} P3=${briefing.stats?.p3Count ?? '?'}`);
  } else {
    console.log('  âœ— latest-briefing.json not found');
  }

  const draftsPath = join(TRIAGE_DIR, 'drafted-responses.json');
  if (existsSync(draftsPath)) {
    const drafts = JSON.parse(readFileSync(draftsPath, 'utf-8'));
    const count = Array.isArray(drafts) ? drafts.length : 0;
    const sample = Array.isArray(drafts) && drafts.length > 0 ? drafts[0] : null;
    const hasRealDrafts = sample && sample.body && sample.body !== 'Hello send' && sample.body.length > 20;
    console.log(`  ${hasRealDrafts ? 'âœ“' : 'âš '} drafted-responses.json â€” ${count} drafts`);
    if (hasRealDrafts) {
      console.log(`    Real bodies: YES`);
      console.log(`    Sample: "${(sample.body || '').substring(0, 100)}..."`);
    } else if (count === 0) {
      console.log('    (Empty â€” no P0/P1 emails in range)');
    } else {
      console.log('    âš  Placeholder bodies detected');
    }
  } else {
    console.log('  âœ— drafted-responses.json not found');
  }

  console.log('\nâœ… Email backfill pipeline complete');
  // WS1: query the graph directly and set exit code 3 on degraded output
  await runVerdict();
  _forensicWrite({ event: 'run_end', status: process.exitCode === 3 ? 'degraded' : 'ok' });
  if (COORDINATED_ENRICH && !process.exitCode) {
    emitCoordinatorEvent({ type: 'enrichment_complete' });
  }
  // Signal dashboard: pipeline complete
  sendIPC({ type: 'pipeline_complete', ts: Date.now() });
}

// â”€â”€ IPC relay: forward watchdog health and phase milestones to dashboard parent â”€â”€
// Only active when this process was spawned by backfill-dashboard.js (process.connected=true).
// The dashboard spawns tsx with stdio=['pipe','pipe','pipe','ipc'] so process.send() works.
//
// Message types emitted upward:
//   { type:'health',   ts, alive, latencyMs, sessions, deltas, memFrac }   â€” from watchdog worker
//   { type:'phase',    ts, phase, label, state }                            â€” phase start/end
//   { type:'metric',   ts, key, value }                                     â€” numeric counter
//   { type:'pipeline_complete', ts }                                        â€” done signal
//   { type:'pipeline_error',    ts, message }                               â€” fatal error

/** Send a structured message to the dashboard parent if connected via IPC. */
function sendIPC(msg: Record<string, unknown>): void {
  try {
    if (process.connected && typeof process.send === 'function') {
      process.send({ ...msg, _elyntic: true });
    }
  } catch { /* non-fatal â€” dashboard may have closed */ }
}

// Forward watchdog health messages (child â†’ parent â†’ grandparent/dashboard)
// The watchdog worker sends { type:'health', ... } and { type:'action', ... } via process.send().
// Since the watchdog worker is a child of THIS process, we receive them here as 'message' events.
// We relay them upward so the dashboard (grandparent) gets live Graph health every ~10s.
process.on('message', (msg: any) => {
  if (!msg || typeof msg !== 'object') return;
  // Relay watchdog health and action messages to the dashboard
  if (msg.type === 'health' || msg.type === 'action' || msg.type === 'heartbeat') {
    sendIPC(msg);
  }
});

function handleBackfillWorkerFailure(err: Error): never {
  process.stderr.write(`[ELYNTIC_DIAG] code=${backfillWorkerDiagnosticCode(err)} severity=error\n`);
  console.error('\nâœ— FATAL:', err.message);
  if (err.stack) console.error(err.stack);
  sendIPC({ type: 'pipeline_error', ts: Date.now(), message: err.message });
  process.exit(1);
}

export function runBackfillWorkerCli(): Promise<void> {
  return runBackfillWorker().catch(handleBackfillWorkerFailure);
}

const invokedPath = process.argv[1] ? resolve(process.argv[1]) : '';
// The body lives in this .mts; launchers still name the internal-backfill-worker.ts shim.
const canonicalPath = resolve(fileURLToPath(import.meta.url));
if (invokedPath === canonicalPath || invokedPath === canonicalPath.replace(/\.mts$/, '.ts')) {
  void runBackfillWorkerCli().then(async () => {
    if (COORDINATED_ENRICH) {
      await exitCoordinatedWorkerAfterFlush(0);
    }
  });
}
