ei-tui 1.6.9 → 1.7.1

package/src/core/persona-tools.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared boolean-map <-> flat-id-array conversion for PersonaEntity.tools.
+ *
+ * PersonaEntity.tools is persisted (and written by external CRUD callers)
+ * as a flat array of ToolDefinition ids. That's opaque to a human or an
+ * external agent — nothing about a bare UUID says which provider it
+ * belongs to, what it's called, or whether it's even grantable right now
+ * (a tool under a disabled provider is unusable regardless of whether its
+ * id sits in this array). buildPersonaToolsMap/resolvePersonaToolsFromMap
+ * convert between that flat storage shape and a self-documenting
+ * `{ [providerDisplayName]: { [toolDisplayName]: boolean } }` map — the
+ * same shape the TUI's $EDITOR/YAML persona editor has used since before
+ * this module existed (originally defined in
+ * tui/src/util/yaml-persona.ts, relocated here so the external CRUD
+ * surface — src/cli/retrieval.ts's lookupById and
+ * src/cli/persona-corrections.ts's create/update — can present and accept
+ * the identical shape instead of a raw UUID array).
+ *
+ * Relocation is verbatim: same names, same signatures, same bodies as the
+ * TUI originals. The TUI now imports both functions from here rather than
+ * defining its own copies.
+ */
+import type { ToolDefinition, ToolProvider } from "./types.js";
+
+export function buildPersonaToolsMap(
+  enabledToolIds: string[],
+  allTools: ToolDefinition[],
+  allProviders: ToolProvider[]
+): Record<string, Record<string, boolean>> | undefined {
+  if (allTools.length === 0) return undefined;
+  const enabledSet = new Set(enabledToolIds);
+  const result: Record<string, Record<string, boolean>> = {};
+  for (const provider of allProviders.filter(p => p.enabled)) {
+    const providerTools = allTools.filter(t => t.provider_id === provider.id);
+    if (providerTools.length === 0) continue;
+    result[provider.display_name] = Object.fromEntries(
+      providerTools.map(t => [t.display_name, enabledSet.has(t.id)])
+    );
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+export function resolvePersonaToolsFromMap(
+  toolsMap: Record<string, Record<string, boolean>> | undefined,
+  allTools: ToolDefinition[],
+  allProviders: ToolProvider[]
+): string[] | undefined {
+  if (!toolsMap) return undefined;
+  const enabledIds: string[] = [];
+  for (const [providerDisplayName, toolToggles] of Object.entries(toolsMap)) {
+    const provider = allProviders.find(p => p.display_name === providerDisplayName);
+    if (!provider) continue;
+    for (const [toolDisplayName, enabled] of Object.entries(toolToggles)) {
+      if (!enabled) continue;
+      const tool = allTools.find(t => t.provider_id === provider.id && t.display_name === toolDisplayName);
+      if (tool) enabledIds.push(tool.id);
+    }
+  }
+  return enabledIds.length > 0 ? enabledIds : [];
+}
+
+/**
+ * A tool id belonging to a currently-disabled provider is invisible to
+ * buildPersonaToolsMap and therefore can never appear in a caller's
+ * submitted map -- not because the caller chose to omit it, but because
+ * they had no way to see it. Full-record-replace semantics only apply to
+ * the portion of tools[] a caller could actually read and edit; anything
+ * outside that boundary must survive an edit unconditionally, or a normal
+ * read-edit-write cycle silently destroys stored state the caller never
+ * had a chance to preserve correctly. This is intentionally NOT a general
+ * merge -- resolvedVisibleIds still fully governs every id whose provider
+ * IS enabled; only ids that are structurally unaddressable right now get
+ * carried forward.
+ */
+export function preserveHiddenToolGrants(
+  resolvedVisibleIds: string[] | undefined,
+  existingIds: string[] | undefined,
+  allTools: ToolDefinition[],
+  allProviders: ToolProvider[]
+): string[] | undefined {
+  const providerById = new Map(allProviders.map(p => [p.id, p]));
+  const toolById = new Map(allTools.map(t => [t.id, t]));
+  const hidden = (existingIds ?? []).filter(id => {
+    const tool = toolById.get(id);
+    if (!tool) return false;
+    const provider = providerById.get(tool.provider_id);
+    return provider ? !provider.enabled : false;
+  });
+  if (hidden.length === 0) return resolvedVisibleIds;
+  const merged = new Set([...(resolvedVisibleIds ?? []), ...hidden]);
+  return merged.size > 0 ? Array.from(merged) : undefined;
+}

package/src/core/processor.ts

@@ -23,10 +23,14 @@ import {
   type ToolDefinition,
   type ToolProvider,
 } from "./types.js";
+import { isReservedPersonaId } from "./types.js";
 import { buildPersonaFromPersonPrompt } from "../prompts/index.js";
 import { buildSiblingAwarenessSection } from "../prompts/room/index.js";
 import type { PersonaGenerationResult } from "../prompts/generation/types.js";
 
+import { readCorrections, assertValidCorrection } from "./corrections.js";
+import type { CorrectionRecord } from "./corrections.js";
+import { withLock, atomicWrite } from "../storage/file-lock.js";
 import type { Storage } from "../storage/interface.js";
 import { remoteSync } from "../storage/remote.js";
 import { yoloMerge } from "../storage/merge.js";
@@ -726,7 +730,115 @@ const toolNextSteps = new Set([
     console.log(`[Processor ${this.instanceId}] runLoop() exited`);
   }
 
+  /**
+   * Drain corrections.json into the live StateManager, every tick (no
+   * time-gating — corrections need near-instant pickup, that's the whole
+   * point of the external write path). Read + apply + delete all happen
+   * inside one withLock() call so a concurrent CLI appendCorrection() can't
+   * race the read-drain-delete sequence and lose a correction appended
+   * mid-drain.
+   *
+   * A malformed record (bad entity_type, or a StateManager call that
+   * throws) is dropped with a loud console.error rather than aborting the
+   * whole batch — corrections.json is external input from CLI/MCP tools
+   * potentially driven by an LLM agent, so one bad record must not wedge
+   * every subsequent correction behind it forever. This mirrors the
+   * existing DLQ/heartbeat error-tolerance philosophy in this file: log
+   * loudly, keep the loop alive, keep draining valid records.
+   */
+  private async drainCorrections(): Promise<void> {
+    if (!this.storage) return;
+    try {
+      const dataPath = this.storage.getDataPath();
+      // Web's IndexedDBStorage/LocalStorage return "" — no filesystem, no
+      // corrections.json to drain. This mechanism is filesystem-only
+      // (TUI/future daemon); Web sessions never write corrections.json in
+      // the first place since the CLI/MCP tools that produce it are Node/Bun-only.
+      if (!dataPath) return;
+      const { join } = await import(/* @vite-ignore */ "path");
+      const correctionsPath = join(dataPath, "corrections.json");
+
+      // Cheap fast path: this runs every 100ms, and readCorrections()
+      // short-circuits on a missing file without touching the lock.
+      const pending = await readCorrections(correctionsPath);
+      if (pending.length === 0) return;
+
+      await withLock(correctionsPath, async () => {
+        // Re-read inside the lock in case a correction was appended between
+        // the unlocked fast-path read above and lock acquisition.
+        const records = await readCorrections(correctionsPath);
+        if (records.length === 0) return;
+
+        for (const record of records) {
+          try {
+            this.applyCorrectionRecord(record);
+          } catch (err) {
+            console.error(`[Processor ${this.instanceId}] Dropping malformed correction record:`, JSON.stringify(record), err);
+          }
+        }
+
+        await atomicWrite(correctionsPath, "[]");
+        this.interface.onHumanUpdated?.();
+      });
+    } catch (err) {
+      console.error(`[Processor ${this.instanceId}] Failed to drain corrections.json:`, err);
+    }
+  }
+
+  /** Dispatch one CorrectionRecord to the matching StateManager upsert/remove call. Throws on an unrecognized entity_type or op (see assertValidCorrection — the same validator the CLI read-merge/self-drain path uses, so a malformed op can never be silently treated as its sibling operation here). */
+  private applyCorrectionRecord(record: CorrectionRecord): void {
+    assertValidCorrection(record);
+    if (record.entity_type === "fact") {
+      if (record.op === "upsert") {
+        this.stateManager.human_fact_upsert(record.record as Fact);
+      } else {
+        this.stateManager.human_fact_remove(record.id);
+      }
+    } else if (record.entity_type === "topic") {
+      if (record.op === "upsert") {
+        this.stateManager.human_topic_upsert(record.record as Topic);
+      } else {
+        this.stateManager.human_topic_remove(record.id);
+      }
+    } else if (record.entity_type === "person") {
+      if (record.op === "upsert") {
+        this.stateManager.human_person_upsert(record.record as Person);
+      } else {
+        this.stateManager.human_person_remove(record.id);
+      }
+    } else if (record.entity_type === "quote") {
+      if (record.op === "upsert") {
+        this.stateManager.human_quote_upsert(record.record as Quote);
+      } else {
+        this.stateManager.human_quote_remove(record.id);
+      }
+    } else if (record.entity_type === "persona") {
+      if (record.op === "upsert") {
+        const existing = this.stateManager.persona_getById(record.id);
+        if (existing) {
+          this.stateManager.persona_replace(record.id, record.record as PersonaEntity);
+        } else {
+          this.stateManager.persona_add(record.record as PersonaEntity);
+        }
+      } else {
+        // Defense in depth — this should never reach here since the
+        // synchronous write-time guard in src/cli/persona-corrections.ts's
+        // removePersonaEntity already rejects a reserved id before ever
+        // queuing the correction. corrections.json is external input,
+        // though, and could theoretically be hand-edited to bypass that.
+        if (isReservedPersonaId(record.id)) {
+          throw new Error(`Cannot delete reserved persona "${record.id}". Use archive instead.`);
+        }
+        this.stateManager.persona_delete(record.id);
+      }
+    } else {
+      throw new Error(`Unrecognized correction entity_type: ${JSON.stringify(record)}`);
+    }
+  }
+
   private async checkScheduledTasks(): Promise<void> {
+    await this.drainCorrections();
+
     const now = Date.now();
 
     const human = this.stateManager.getHuman();
@@ -1291,7 +1403,7 @@ const toolNextSteps = new Set([
   }
 
   async upsertPerson(person: Person): Promise<void> {
-    const sanitized = { ...person, identifiers: sanitizeEiPersonaIdentifiers(person.identifiers ?? [], this.stateManager) };
+    const sanitized = { ...person, identifiers: sanitizeEiPersonaIdentifiers(person.identifiers ?? [], this.stateManager.persona_getAll()) };
     await upsertPerson(this.stateManager, sanitized);
     this.interface.onHumanUpdated?.();
   }

package/src/core/state/human.ts

@@ -118,6 +118,16 @@ export class HumanState {
      return false;
    }
 
+   quote_upsert(quote: Quote): void {
+     const idx = this.human.quotes.findIndex((q) => q.id === quote.id);
+     if (idx >= 0) {
+       this.human.quotes[idx] = quote;
+     } else {
+       this.human.quotes.push(quote);
+     }
+     this.human.last_updated = new Date().toISOString();
+   }
+
    quote_add(quote: Quote): void {
      if (!quote.created_at) {
        quote.created_at = new Date().toISOString();

package/src/core/state/personas.ts

@@ -80,6 +80,14 @@ export class PersonaState {
     return true;
   }
 
+  /** Full replace of a persona's entity (not a merge) — used by the live-drain path for corrections-queue upserts, where record.record is already a complete PersonaEntity and any field genuinely absent from it must NOT survive from the prior value. Preserves .messages untouched, same as update(). */
+  replace(personaId: string, entity: PersonaEntity): boolean {
+    const data = this.personas.get(personaId);
+    if (!data) return false;
+    data.entity = { ...entity, last_updated: new Date().toISOString() };
+    return true;
+  }
+
   archive(personaId: string): boolean {
     const data = this.personas.get(personaId);
     if (!data) return false;

package/src/core/state-manager.ts

@@ -715,6 +715,11 @@ export class StateManager {
     this.scheduleSave();
   }
 
+  human_quote_upsert(quote: Quote): void {
+    this.humanState.quote_upsert(quote);
+    this.scheduleSave();
+  }
+
   human_quote_update(id: string, updates: Partial<Quote>): boolean {
     const result = this.humanState.quote_update(id, updates);
     this.scheduleSave();
@@ -758,6 +763,12 @@ export class StateManager {
     return result;
   }
 
+  persona_replace(personaId: string, entity: PersonaEntity): boolean {
+    const result = this.personaState.replace(personaId, entity);
+    this.scheduleSave();
+    return result;
+  }
+
   persona_archive(personaId: string): boolean {
     const result = this.personaState.archive(personaId);
     this.scheduleSave();

package/src/core/utils/identifier-utils.ts

@@ -1,4 +1,5 @@
 import type { PersonIdentifier } from "../types/data-items.js";
+import type { PersonaEntity } from "../types/entities.js";
 import type { StateManager } from "../state-manager.js";
 import { BUILT_IN_IDENTIFIER_TYPES } from "../constants/built-in-identifier-types.js";
 
@@ -29,12 +30,12 @@ export function normalizeIdentifierType(llmType: string, state: StateManager): s
 
 export function sanitizeEiPersonaIdentifiers(
   identifiers: PersonIdentifier[],
-  state: StateManager
+  personas: PersonaEntity[]
 ): PersonIdentifier[] {
   return identifiers.map(id => {
     if (id.type !== 'Ei Persona' && id.type !== 'AI Persona') return id;
     if (UUID_REGEX.test(id.value)) return { ...id, type: 'Ei Persona' };
-    const matched = state.persona_getAll().find(p =>
+    const matched = personas.find(p =>
       p.display_name === id.value || p.aliases?.includes(id.value)
     );
     if (matched) return { ...id, type: 'Ei Persona', value: matched.id };

package/src/prompts/human/person-scan.ts

@@ -107,6 +107,8 @@ If you are unsure of the type, use \`Nickname\` as a fallback. Do NOT invent typ
 
 Only include \`identifiers\` when explicitly mentioned in the conversation — omit it entirely if nothing qualifies.
 
+Do NOT attribute one person's handle or identifier to another person discussed in the same window. If "Marcus's GitHub is @mcodes" appears alongside a mention of Priya, @mcodes belongs to Marcus's record only — never Priya's.
+
 ## Confidence & Relationship Type
 
 For each person, rate how important they are to the human user's life:

package/src/prompts/human/person-update.ts

@@ -1,5 +1,6 @@
 import type { PromptOutput, ParticipantContext } from "./types.js";
 import type { Person, Message } from "../../core/types.js";
+import type { PersonIdentifier } from "../../core/types/data-items.js";
 import { formatMessagesAsPlaceholders } from "../message-utils.js";
 
 export interface PersonUpdatePromptData {
@@ -12,6 +13,7 @@ export interface PersonUpdatePromptData {
   persona_name: string;
   participant_context?: ParticipantContext;
   known_identifier_types?: string[];
+  suggested_identifiers?: PersonIdentifier[];
 }
 
 function participantContextSection(ctx: ParticipantContext | undefined): string {
@@ -171,20 +173,29 @@ The description should NOT:
     ? `CRITICAL: The HUMAN USER is ${humanName}. They wrote these messages. Do NOT assign their names, nicknames, or handles as identifiers for this person's record — UNLESS this IS the user's own Self record (relationship: "Self").`
     : `CRITICAL: The HUMAN USER wrote these messages. Do NOT assign their own names or handles as identifiers for this person's record — UNLESS this IS the user's own Self record (relationship: "Self"). Do NOT return \`relationship: "Self"\` unless you are certain this record is about the human user themselves.`;
 
+  const attributionGuard = `\nONLY add an identifier if it is explicitly stated about THIS SPECIFIC PERSON — not inferred from proximity in the conversation. If two different people are discussed near each other, do NOT attribute one person's handle, email, or name to the other.`;
   const isUnknownNewPerson = isNewItem && personName === 'Unknown';
   const unknownIdentifierGuard = isUnknownNewPerson
-    ? `\nThis person's name is not yet known. ONLY add \`identifiers\` if their name, handle, or email is explicitly stated in the conversation about THEM specifically — not inferred, not guessed.`
+    ? `\nThis person's name is not yet known — be especially careful: only record an identifier the conversation names for THEM specifically.`
     : '';
 
-  const identifierSection = `${identityGuard}${unknownIdentifierGuard}
+  const suggestedIdentifiers = data.suggested_identifiers ?? [];
+  const suggestedIdentifiersBlock = !isNewItem && suggestedIdentifiers.length > 0
+    ? `\n\nThe scan flagged these identifiers as POSSIBLY belonging to this person: ${suggestedIdentifiers.map(i => `\`${i.type}=${i.value}\``).join(', ')}.
+For EACH, add it to \`identifiers_to_add\` ONLY if the Most Recent Messages confirm it belongs to THIS SPECIFIC PERSON. If any actually belongs to someone else mentioned in the conversation, omit it. Do not add any you cannot confirm from the conversation.`
+    : '';
+
+  const identifierSection = `${identityGuard}${attributionGuard}${unknownIdentifierGuard}
 
 If you spot a platform handle, username, email, nickname, or full name explicitly mentioned in the conversation that isn't already in the person's identifiers, include it in \`identifiers_to_add\` (updates) or \`identifiers\` (new records). Always mark exactly one identifier as \`"is_primary": true\` — prefer the most formal or complete name.
 
+Example of what NOT to do: if the conversation says "I talked to Priya and Marcus — Marcus's GitHub is @mcodes", do NOT add @mcodes to Priya's record; it belongs to Marcus only.
+
 For persons with a known relationship (Father, Mother, Sibling, etc.), also look for informal terms the HUMAN USER uses to address or refer to THAT SPECIFIC PERSON (\`Dad\`, \`Pop\`, \`Mom\`, \`Sis\`, etc.) and add them as \`{ "type": "Relationship", "value": "..." }\` identifiers.
 
 NEVER add dates, ages, birthdays, or anniversaries as identifiers. These are not identifying labels — if known, include them in the description instead.
 
-Known identifier types: ${allTypes}. If unsure of type, use \`Nickname\`.`;
+Known identifier types: ${allTypes}. If unsure of type, use \`Nickname\`.${suggestedIdentifiersBlock}`;
 
   // ── OUTPUT FORMAT ─────────────────────────────────────────────────────────
 

package/src/storage/file-lock.ts

@@ -0,0 +1,120 @@
+/**
+ * File-based advisory locking + atomic writes, shared by any Storage
+ * implementation (and CLI tooling) that needs to serialize writes to a
+ * JSON file on disk without a database.
+ *
+ * Extracted from tui/src/storage/file.ts so the CLI's corrections.json
+ * writer/drainer can use identical lock semantics instead of forking a
+ * second implementation.
+ *
+ * fs/promises is imported dynamically per-function, not statically at
+ * module scope: this module is transitively imported by src/core/corrections.ts
+ * -> src/core/processor.ts, which Web's Vite build bundles for the browser.
+ * A static `import { readFile } from "fs/promises"` makes rollup try to
+ * resolve named exports against Vite's browser-externalized stub, which
+ * has none — that's a hard build failure, not a runtime one (same pattern
+ * already used in src/cli.ts and src/cli/install.ts for this exact reason).
+ */
+
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_RETRY_DELAY_MS = 50;
+
+// Plain executor form, not Promise.withResolvers — this module runs on
+// whatever Node the CLI/TUI ships with, and withResolvers only landed in
+// Node 22. No behavior difference, just broader runtime compatibility.
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function getLockPath(filePath: string): string {
+  return `${filePath}.lock`;
+}
+
+/**
+ * Acquire an advisory lock on filePath. Stale locks (older than
+ * LOCK_TIMEOUT_MS) are broken automatically. Returns false if the lock
+ * could not be acquired within LOCK_TIMEOUT_MS.
+ */
+export async function acquireLock(filePath: string): Promise<boolean> {
+  const { readFile, writeFile, unlink } = await import(/* @vite-ignore */ "fs/promises");
+  const lockPath = getLockPath(filePath);
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < LOCK_TIMEOUT_MS) {
+    // readFile throws ENOENT when the lock is absent — treated the same as
+    // "lock vanished mid-read" below: proceed straight to acquire.
+    let lockContent: string | null = null;
+    try {
+      lockContent = await readFile(lockPath, "utf-8");
+    } catch {
+      lockContent = null;
+    }
+
+    if (lockContent !== null) {
+      const lockTime = parseInt(lockContent, 10);
+      if (!isNaN(lockTime) && Date.now() - lockTime > LOCK_TIMEOUT_MS) {
+        try {
+          await unlink(lockPath);
+        } catch {}
+      } else {
+        await delay(LOCK_RETRY_DELAY_MS);
+        continue;
+      }
+    }
+
+    try {
+      // "wx" = exclusive create, fails with EEXIST if the path already
+      // exists. Without this flag, two callers that both observed the lock
+      // as absent (the check above) could both reach this writeFile and
+      // both succeed — writeFile has no atomicity of its own, it just
+      // overwrites. "wx" makes the write itself the atomic test-and-set:
+      // only one caller can win it, the other gets EEXIST and falls into
+      // the catch below to retry from the top of the loop.
+      await writeFile(lockPath, Date.now().toString(), { flag: "wx" });
+      return true;
+    } catch {
+      await delay(LOCK_RETRY_DELAY_MS);
+    }
+  }
+
+  return false;
+}
+
+export async function releaseLock(filePath: string): Promise<void> {
+  const { unlink } = await import(/* @vite-ignore */ "fs/promises");
+  const lockPath = getLockPath(filePath);
+  try {
+    await unlink(lockPath);
+  } catch {}
+}
+
+/**
+ * Run fn() while holding filePath's advisory lock. Throws
+ * STORAGE_LOCK_TIMEOUT if the lock can't be acquired in time.
+ */
+export async function withLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+  const acquired = await acquireLock(filePath);
+  if (!acquired) {
+    throw new Error("STORAGE_LOCK_TIMEOUT: Could not acquire file lock");
+  }
+  try {
+    return await fn();
+  } finally {
+    await releaseLock(filePath);
+  }
+}
+
+/** Write content to filePath via temp-file + rename, so readers never see a partial write. */
+export async function atomicWrite(filePath: string, content: string): Promise<void> {
+  const { writeFile, rename, unlink } = await import(/* @vite-ignore */ "fs/promises");
+  const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+  try {
+    await writeFile(tempPath, content);
+    await rename(tempPath, filePath);
+  } catch (e) {
+    try {
+      await unlink(tempPath);
+    } catch {}
+    throw e;
+  }
+}

package/tui/README.md

@@ -174,6 +174,8 @@ Rooms have three modes, set at creation time:
 | `/tools` | | Manage tool providers — enable/disable tools per persona |
 | `/auth <service>` | | Authenticate with an external service via OAuth. Supported: `spotify`, `slack` |
 
+> Disabling a tool provider hides its tools from `/details`' YAML editor, but doesn't revoke them — a persona's grants for a disabled provider's tools survive an unrelated `/details` edit and reappear once you re-enable the provider with `/tools` or `/provider`.
+
 ### Editor
 
 | Command | Aliases | Description |

package/tui/src/commands/provider.tsx

@@ -48,7 +48,7 @@ export async function openModelOverlay(ctx: Parameters<Command["execute"]>[1]):
   const models = await buildModelList(ctx);
 
   if (models.length === 0) {
-    ctx.showNotification("No models configured. Use /provider new to create one.", "info");
+    await createProviderViaEditor(ctx);
     return;
   }
 

package/tui/src/components/WelcomeOverlay.tsx

@@ -90,9 +90,9 @@ export function WelcomeOverlay(props: WelcomeOverlayProps) {
         <box visible={!hasAny()} flexDirection="column">
           <text fg="#dc322f">No LLM provider detected.</text>
           <text> </text>
-          <text fg="#93a1a1">Start LMStudio (port 1234) or Ollama (port 11434), or</text>
-          <text fg="#93a1a1">set one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY,</text>
-          <text fg="#93a1a1">MISTRAL_API_KEY, GEMINI_API_KEY and restart.</text>
+          <text fg="#93a1a1">Use /provider new to configure one manually, or</text>
+          <text fg="#93a1a1">start LMStudio (port 1234) / Ollama (port 11434), or</text>
+          <text fg="#93a1a1">set ANTHROPIC_API_KEY, OPENAI_API_KEY, etc. and restart.</text>
         </box>
 
         <text> </text>

package/tui/src/context/ei.tsx

@@ -3,6 +3,7 @@ import {
   useContext,
   onMount,
   onCleanup,
+  For,
   Match,
   Switch,
   createSignal,
@@ -183,6 +184,7 @@ export const EiProvider: ParentComponent = (props) => {
   const [showWelcomeOverlay, setShowWelcomeOverlay] = createSignal(false);
   const [detectedProviders, setDetectedProviders] = createSignal<ProviderDetectionStatus[]>([]);
   const [firstBootDefaultModel, setFirstBootDefaultModel] = createSignal<string | undefined>(undefined);
+  const [bootError, setBootError] = createSignal<string | null>(null);
   const [conflictData, setConflictData] = createSignal<StateConflictData | null>(null);
 
   let processor: Processor | null = null;
@@ -970,6 +972,7 @@ export const EiProvider: ParentComponent = (props) => {
       await finishBootstrap();
     } catch (err: any) {
       logger.error(`bootstrap() failed: ${err?.message || err}`);
+      setBootError(err?.message || String(err));
     }
   }
 
@@ -1089,6 +1092,17 @@ export const EiProvider: ParentComponent = (props) => {
       <Match when={store.ready}>
         <EiContext.Provider value={value}>{props.children}</EiContext.Provider>
       </Match>
+      <Match when={bootError()}>
+        <box width="100%" height="100%" justifyContent="center" alignItems="center" flexDirection="column">
+          <text fg="#dc322f">Ei failed to start</text>
+          <text> </text>
+          <For each={bootError()!.split('\n')}>
+            {(line) => <text fg="#93a1a1">{line || " "}</text>}
+          </For>
+          <text> </text>
+          <text fg="#586e75">Press Ctrl+C to exit</text>
+        </box>
+      </Match>
       <Match when={!store.ready}>
         <box width="100%" height="100%" justifyContent="center" alignItems="center">
           <text>Loading Ei...</text>

package/tui/src/index.tsx

@@ -14,7 +14,19 @@ if (args.includes("--version") || args.includes("version") || args.includes("-v"
 
 const storage = new FileStorage(Bun.env.EI_DATA_PATH);
 const lock = new InstanceLock(storage.getDataPath());
-const lockResult = await lock.acquire();
+const lockResult = await lock.acquire().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  const dataPath = storage.getDataPath();
+  process.stderr.write(
+    `\nEi cannot start: cannot write to data directory.\n\n` +
+    `  Path:  ${dataPath}\n` +
+    `  Error: ${msg}\n\n` +
+    `Fix options:\n` +
+    `  - Fix Permissions  (sudo chown $USER $EI_DATA_PATH)\n` +
+    `  - Change Data Path (EI_DATA_PATH=~/ei-data ei)\n\n`
+  );
+  process.exit(1);
+});
 
 if (!lockResult.acquired) {
   process.stderr.write(