ei-tui 1.6.8 → 1.7.0

package/src/cli/README.md

@@ -15,9 +15,12 @@ ei --recent                            # Most recently mentioned items (no query
 ei --persona "Beta" --recent           # Most recently mentioned items Beta has learned
 ei --id <id>                   # Look up entity by ID — or fetch a message by FQ ID
 echo <id> | ei --id            # Look up entity by ID from stdin
-ei --install                   # Wire Ei into Claude Code, Cursor, Codex, and OpenCode (MCP + hooks + persona plugin)
+ei --install                   # Wire Ei into Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks + skills (ei-curate, ei-persona, and future shipped skills) + persona plugin where supported)
 ei --sync                      # Pull latest state from remote sync server into state.backup.json (no TUI required)
 ei mcp                         # Start the Ei MCP stdio server (for Claude Code/Cursor/Codex)
+ei create <type> --json '<json>'       # Create a new entity (fact/topic/person/persona)
+ei update <type> <id> --json '<json>'  # Replace an entity by ID (fact/topic/person/quote/persona)
+ei remove <type> <id>                  # Remove an entity by ID
 ```
 
 Type aliases: `fact`, `person`, `topic`, `quote`, `persona` all work (singular or plural).
@@ -109,6 +112,9 @@ The MCP server exposes these tools to Claude Code, Cursor, Codex, and OpenCode:
 | `ei_search` | Search across all five data types (facts, topics, people, quotes, personas). Supports `type`, `persona`, `source`, `recent`, `limit` filters. Start here. |
 | `ei_lookup` | Full-record lookup for any entity by ID — facts, topics, people, quotes, or personas. Use when you need complete details beyond the search summary. |
 | `ei_fetch_message` | Retrieve a specific message by fully-qualified ID with optional `before`/`after` context window. Use when a quote result has a `message_id` and you want the original conversation. Routes to the correct source automatically. |
+| `ei_create` | Create a new entity (fact, topic, person, or persona). Pass a full JSON record matching the entity's schema. Validates server-side; unknown fields are rejected. Returns the assigned id and the full stored record. Not available for quotes — verifiable-origin data can only be corrected via `ei_update`, never created. |
+| `ei_update` | Replace an entity by ID. Full-record replacement — fetch first with `ei_lookup`, edit the fields you need to change, and pass the complete record back. Any omitted field is treated as absent, not "leave unchanged". Supports fact, topic, person, quote, and persona. |
+| `ei_remove` | Permanently remove a fact, topic, person, or persona by ID. Use to drop bad extracted data that shouldn't be corrected, just deleted, or to delete a persona that's no longer needed. Not available for quotes. Reserved built-in personas ("ei", "emmet") can't be removed this way — use `ei_update` to set `is_archived: true` instead. |
 
 ### `ei_search` arguments
 
@@ -133,7 +139,55 @@ All search commands return arrays. Each result includes a `type` field.
 
 **Persona**: `{ type, id, display_name, short_description, model, base_prompt, traits[], topics[] }`
 
-**ID lookup** (`lookup: true`): single object (not an array) with the same shape.
+**ID lookup** (`ei --id <id>` / `ei_lookup`): single object (not an array) with the same shape as above, plus a `linked_quotes` array for Fact, Topic, and Person records — quotes attributed to that entity, useful when auditing what was said about a person or topic. Persona ID lookups additionally get a `tools` field: the raw `tools` id array is replaced with a self-documenting `{ providerDisplayName: { toolDisplayName: boolean } }` map, so an agent can see exactly what's granted (and what else is grantable) without a separate lookup.
+
+## Memory Management
+
+`ei create`, `ei update`, and `ei remove` let you correct Ei's knowledge base directly — from the CLI or via MCP tools in your coding agent.
+
+### Which types support which operations
+
+| Type | create | update | remove |
+|------|--------|--------|--------|
+| fact | yes | yes | yes |
+| topic | yes | yes | yes |
+| person | yes | yes | yes |
+| quote | — | yes | — |
+| persona | yes | yes | yes |
+
+Quotes are created only by Ei's extraction pipeline (verifiable-origin data). They can be updated to repoint `data_item_ids` after a split/merge or to fix mistranscribed text, but never created or removed via these commands.
+
+Personas support all three operations too, but through a separate schema (`PersonaEntity`, not the fact/topic/person `DataItemBase` shape) — see the `ei create/update/remove persona` examples below and the `ei-persona` skill for guided authoring.
+
+### Update semantics: full replacement, not a patch
+
+`ei update` replaces the entire record. Any field you omit is gone. The safe pattern:
+
+```sh
+# 1. Fetch the current record
+ei --id abc-123
+
+# 2. Edit only the fields you want to change, then submit the whole thing
+ei update fact abc-123 --json '{"name":"Field of Study","description":"Software Engineering / CS","sentiment":0,"validated_date":"2026-03-16T22:46:03.367Z"}'
+```
+
+### Examples (from `ei --help`)
+
+```sh
+ei create fact --json '{"name":"Field of Study","description":"CS","sentiment":0,"validated_date":""}'
+ei update fact abc-123 --json '{"name":"Field of Study","description":"Updated","sentiment":0,"validated_date":""}'
+ei update quote <id> --json '{"data_item_ids":["person-b-id"], ...}'  # Repoint a quote after splitting a bad merge (fetch the full record via 'ei --id <id>' first)
+ei create persona --json '{"display_name":"Yoda","long_description":"Speaks in inverted syntax, wise and patient.","traits":[{"name":"Inverted speech","description":"Talks like Yoda","sentiment":0.7}],"topics":[]}'
+ei update persona <id> --json '<full persona record from ei --id <id>, edited>'
+ei remove persona abc-123              # Remove a persona (reserved personas like "ei"/"emmet" must be archived instead)
+ei remove fact abc-123
+```
+
+### Corrections queue
+
+Changes written by `ei create/update/remove` (and the MCP tools `ei_create/ei_update/ei_remove`) go through a corrections queue (`$EI_DATA_PATH/corrections.json`). If a live Ei instance (TUI or daemon) is running, the Processor drains this file on every runLoop tick and applies changes to the live StateManager — no TUI restart required. If nothing is running, the write applies straight to `state.json` instead of waiting for a TUI session that may not start for days.
+
+For safe, agent-driven curation with verification guardrails, use the `ei-curate` skill (see [Shipped Skills](#shipped-skills) below).
 
 ## Quick Sync
 
@@ -146,3 +200,19 @@ ei --sync
 Pulls the latest state from your remote sync server and saves it to `state.backup.json`. Works the same credential hierarchy as the TUI: reads from `state.backup.json` first, falls back to `EI_SYNC_USERNAME` / `EI_SYNC_PASSPHRASE` environment variables if not present.
 
 Will abort (with a clear error) if `state.json` already exists on this machine — that means Ei has run here and a conflict resolution step would be needed on next launch.
+
+## Shipped Skills
+
+`ei --install` copies Ei's shipped skills into each harness's skill discovery directory alongside the MCP config and context hooks:
+
+- **Claude Code / OMP**: `~/.config/opencode/skills/<skill-name>/`
+- Other tools: respective skill directories per harness
+
+Skills are installed automatically — any directory added under `skills/` in the Ei package gets copied on the next `ei --install` run.
+
+### Currently shipped
+
+| Skill | What it does |
+|-------|-------------|
+| `ei-curate` | Safe agent-driven memory curation. Provides verified workflows for fixing merged records, bad attributions, stale facts, and mis-attributed quotes — using `ei create/update/remove` with explicit confirmation before every write. Read the full workflow at `skills/ei-curate/SKILL.md`. Load it in your harness with `/ei-curate`. |
+| `ei-persona` | Safe agent-driven persona authoring. Guides creating, editing (traits/topics/description), archiving, or deleting a persona's *character* via `ei create/update/remove persona` — distinct from `ei-curate`, which corrects learned data rather than authoring identity. Read the full workflow at `skills/ei-persona/SKILL.md`. Load it in your harness with `/ei-persona`. |

package/src/cli/commands/personas.ts

@@ -1,4 +1,4 @@
-import { loadLatestState, retrievePersonas, retrievePersonasSemantic } from "../retrieval";
+import { loadLatestState, retrievePersonas, retrievePersonasSemantic, mapPersona } from "../retrieval";
 import { getEmbeddingService } from "../../core/embedding-service";
 import type { PersonaResult } from "../retrieval";
 
@@ -14,8 +14,53 @@ export async function execute(query: string, limit: number, options: { recent?:
     return nameResults;
   }
 
+  // BUG-2 fix: query may be longer than the stored persona name
+  // (e.g. "Beta — QA Goddess" vs stored "Beta"). Try reverse containment
+  // before falling to semantic search, which requires an embedding.
+  const queryLower = query.toLowerCase();
+  const reverseResults = Object.values(state.personas)
+    .map((p) => p.entity)
+    .filter((p) => queryLower.includes(p.display_name.toLowerCase()))
+    .slice(0, limit)
+    .map(mapPersona);
+  if (reverseResults.length > 0) {
+    return reverseResults;
+  }
+
   const embeddingService = getEmbeddingService();
   const queryVector = await embeddingService.embed(query);
   const semanticResults = await retrievePersonasSemantic(queryVector, state, limit);
   return semanticResults;
 }
+
+/**
+ * Format a PersonaResult as a <ei-relationship> block for injection into
+ * AI system prompts. Equivalent to the jq formatter in .zshenv.omp and
+ * the inline builder previously in the OpenCode plugin — consolidated here
+ * so all integrations can call `ei personas <name> --format prompt`.
+ */
+export function buildEiRelationshipBlock(persona: PersonaResult): string {
+  const strongTraits = (persona.traits ?? [])
+    .filter((t) => t.strength >= 0.7)
+    .sort((a, b) => b.strength - a.strength)
+    .map((t) => `**${t.name}** (${Math.round(t.strength * 100)}%): ${t.description}`)
+    .join("\n");
+  const sortedTopics = [...(persona.topics ?? [])]
+    .sort((a, b) => b.exposure_current - a.exposure_current)
+    .map((t) => `**${t.name}**: ${t.perspective} — ${t.approach}`)
+    .join("\n");
+  return [
+    "<!-- ei-relationship-injected -->",
+    "<ei-relationship>",
+    "## Ei: Relationship Context",
+    "",
+    persona.base_prompt ?? "",
+    "",
+    "### Working Style",
+    strongTraits || "(no traits above threshold)",
+    "",
+    "### Shared Context",
+    sortedTopics || "(no topics)",
+    "</ei-relationship>",
+  ].join("\n");
+}

package/src/cli/corrections-endpoints.ts

@@ -0,0 +1,297 @@
+/**
+ * Validated create/update/remove endpoints for ei_create, ei_update, and
+ * ei_remove — shared by the CLI subcommands (src/cli.ts) and the MCP tools
+ * (src/cli/mcp.ts) so both surfaces enforce identical schemas and produce
+ * identical CorrectionRecords.
+ *
+ * Every accepted entity is fully materialized here — id assigned (create),
+ * embedding computed, Person identifiers sanitized and name-synced — before
+ * being handed to writeCorrection(). Callers of ei_update must round-trip
+ * a full record obtained from ei_lookup: unset optional fields are treated
+ * as absent, not "leave existing value alone" (full-replacement semantics —
+ * see design discussion for why partial-field patching isn't safe here).
+ */
+
+import { z } from "zod";
+import { loadLatestState } from "./retrieval.js";
+import { writeCorrection } from "./corrections-writer.js";
+import { sanitizeEiPersonaIdentifiers } from "../core/utils/identifier-utils.js";
+import { computeDataItemEmbedding, computeQuoteEmbedding } from "../core/embedding-service.js";
+import type { CorrectableType, CorrectionRecord } from "../core/corrections.js";
+import type { Fact, Topic, Person, Quote } from "../core/types.js";
+import type { PersonaEntity } from "../core/types/entities.js";
+
+// Fact/topic/person handling below is keyed by this narrower alias, not the
+// full CorrectableType — parseInput/buildAndWriteUpsert only ever validate
+// and materialize these 3 types. Quotes get their own updateQuoteEntity path
+// (different embedding source, no last_updated field, update-only by design)
+// rather than flowing through this shared machinery.
+type NonQuoteType = "fact" | "topic" | "person";
+
+export const CORRECTABLE_TYPES: CorrectableType[] = ["fact", "topic", "person"];
+// Wider set accepted by the `update` surface only — a Quote can be corrected
+// (data_item_ids repointed after a split/merge, mistranscribed text fixed)
+// but, per design, never created or removed, so create/remove keep gating on
+// CORRECTABLE_TYPES above while update alone widens to this constant.
+export const UPDATABLE_TYPES: CorrectableType[] = ["fact", "topic", "person", "quote"];
+
+// Metadata fields common to all three entity types, all server-preserved
+// pass-through — a caller round-tripping ei_lookup output keeps them
+// unless they deliberately edit/clear them.
+const metaFields = {
+  learned_on: z.string().optional(),
+  last_mentioned: z.string().optional(),
+  learned_by: z.string().optional(),
+  last_changed_by: z.string().optional(),
+  interested_personas: z.array(z.string()).optional(),
+  sources: z.array(z.string()).optional(),
+  persona_groups: z.array(z.string()).optional(),
+  rewrite_length_floor: z.number().optional(),
+};
+
+const factSchema = z.strictObject({
+  name: z.string().min(1),
+  description: z.string(),
+  sentiment: z.number().min(-1).max(1),
+  validated_date: z.string(),
+  ...metaFields,
+});
+
+const topicSchema = z.strictObject({
+  name: z.string().min(1),
+  description: z.string(),
+  sentiment: z.number().min(-1).max(1),
+  category: z.string().optional(),
+  exposure_current: z.number().min(0).max(1).default(0),
+  exposure_desired: z.number().min(0).max(1).default(0.5),
+  last_ei_asked: z.string().nullable().optional(),
+  ...metaFields,
+});
+
+const identifierSchema = z.strictObject({
+  type: z.string().min(1),
+  value: z.string().min(1),
+  is_primary: z.boolean().optional(),
+});
+
+const personSchema = z.strictObject({
+  name: z.string().optional(),
+  description: z.string(),
+  sentiment: z.number().min(-1).max(1),
+  identifiers: z.array(identifierSchema).optional(),
+  validated_date: z.string().optional(),
+  relationship: z.string().default(""),
+  exposure_current: z.number().min(0).max(1).default(0),
+  exposure_desired: z.number().min(0).max(1).default(0.5),
+  last_ei_asked: z.string().nullable().optional(),
+  ...metaFields,
+}).refine(
+  (p) => (p.identifiers && p.identifiers.length > 0) || (p.name && p.name.length > 0),
+  { message: "Person requires at least one identifier or a name" }
+);
+
+const quoteSchema = z.strictObject({
+  message_id: z.string().nullable(),
+  data_item_ids: z.array(z.string()),
+  persona_groups: z.array(z.string()),
+  text: z.string().min(1),
+  speaker: z.string().min(1),
+  channel: z.string().optional(),
+  timestamp: z.string(),
+  start: z.number().nullable(),
+  end: z.number().nullable(),
+  created_at: z.string(),
+  created_by: z.enum(["extraction", "human"]),
+});
+export type QuoteInput = z.infer<typeof quoteSchema>;
+
+const SCHEMAS = { fact: factSchema, topic: topicSchema, person: personSchema } as const;
+
+export type FactInput = z.infer<typeof factSchema>;
+export type TopicInput = z.infer<typeof topicSchema>;
+export type PersonInput = z.infer<typeof personSchema>;
+
+/** Thrown on schema violations — callers should surface `.message` directly, not swallow it. */
+export class CorrectionValidationError extends Error {}
+
+/**
+ * Strip the embedding vector before handing a just-written record back to a
+ * caller. writeCorrection() needs the real embedding (computed above) to
+ * persist for search — this only shapes the CLI/MCP *response*, mirroring
+ * lookupById's read-path convention (retrieval.ts) of never surfacing a raw
+ * float array to a consumer that has no use for it. Safe to strip after the
+ * fact: writeCorrection() has already awaited and fully persisted by the
+ * time each call site below runs this.
+ */
+function stripEmbedding<T extends { embedding?: number[] }>(record: T): T {
+  const { embedding, ...rest } = record;
+  void embedding;
+  return rest as T;
+}
+
+/**
+ * Server-owned fields that ei_lookup returns on every entity and that a
+ * caller following the documented ei_lookup -> edit -> ei_update round-trip
+ * will send straight back. Stripped before schema validation so the
+ * round-trip actually works — id/last_updated are always server-assigned
+ * (the id param and a fresh timestamp win, never a caller-supplied value),
+ * `type` is `lookupById`'s own discriminator, never a real entity field,
+ * and `linked_quotes` is a read-only reverse-index (which quotes reference
+ * this entity) that lookupById computes on the fly for fact/topic/person —
+ * never a field a caller is meant to set. Any OTHER unknown key still fails
+ * validation — this is a narrow allowlist, not permissive parsing.
+ */
+const ROUND_TRIP_FIELDS = ["id", "type", "last_updated", "linked_quotes"] as const;
+
+function parseInput(entityType: NonQuoteType, body: unknown, mode: "create" | "update"): FactInput | TopicInput | PersonInput {
+  let input: unknown = body;
+  if (mode === "update" && body && typeof body === "object") {
+    const stripped: Record<string, unknown> = { ...body };
+    for (const field of ROUND_TRIP_FIELDS) {
+      delete stripped[field];
+    }
+    input = stripped;
+  }
+  const result = SCHEMAS[entityType].safeParse(input);
+  if (!result.success) {
+    throw new CorrectionValidationError(
+      `Invalid ${entityType}: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return result.data;
+}
+
+/**
+ * Materialize a validated input into a full entity record (id, name-synced
+ * identifiers, embedding) and persist it as an upsert correction. Shared by
+ * createEntity (fresh id) and updateEntity (caller-supplied id) — both
+ * need identical Person identifier sanitization and embedding computation.
+ */
+async function buildAndWriteUpsert(
+  entityType: NonQuoteType,
+  id: string,
+  parsed: FactInput | TopicInput | PersonInput,
+  personas: PersonaEntity[]
+): Promise<Fact | Topic | Person> {
+  const now = new Date().toISOString();
+
+  let record: Fact | Topic | Person;
+  if (entityType === "person") {
+    const input = parsed as PersonInput;
+    const identifiers = sanitizeEiPersonaIdentifiers(input.identifiers ?? [], personas);
+    const primary = identifiers.find((i) => i.is_primary) ?? identifiers[0];
+    const name = primary?.value ?? input.name ?? "";
+    record = { ...input, id, identifiers, name, last_updated: now } as Person;
+  } else {
+    record = { ...parsed, id, last_updated: now } as Fact | Topic;
+  }
+
+  record.embedding = await computeDataItemEmbedding(record);
+
+  const correction: CorrectionRecord = { op: "upsert", entity_type: entityType, id, record, timestamp: now };
+  await writeCorrection(correction);
+  return record;
+}
+
+export async function createEntity(
+  entityType: CorrectableType,
+  body: unknown
+): Promise<{ id: string; record: Fact | Topic | Person }> {
+  const parsed = parseInput(entityType as NonQuoteType, body, "create");
+  const state = await loadLatestState();
+  if (!state) {
+    throw new Error("No saved state found. Is EI_DATA_PATH set correctly?");
+  }
+
+  const id = crypto.randomUUID();
+  const record = await buildAndWriteUpsert(entityType as NonQuoteType, id, parsed, Object.values(state.personas).map((p) => p.entity));
+  return { id, record: stripEmbedding(record) };
+}
+
+export async function updateEntity(
+  entityType: CorrectableType,
+  id: string,
+  body: unknown
+): Promise<Fact | Topic | Person | Quote> {
+  if (entityType === "quote") {
+    return updateQuoteEntity(id, body);
+  }
+
+  const parsed = parseInput(entityType, body, "update");
+  const state = await loadLatestState();
+  if (!state) {
+    throw new Error("No saved state found. Is EI_DATA_PATH set correctly?");
+  }
+
+  const array = entityType === "fact" ? state.human.facts : entityType === "topic" ? state.human.topics : state.human.people;
+  if (!array.some((item: { id: string }) => item.id === id)) {
+    throw new Error(`No ${entityType} found with id: ${id}`);
+  }
+
+  return stripEmbedding(await buildAndWriteUpsert(entityType, id, parsed, Object.values(state.personas).map((p) => p.entity)));
+}
+
+/**
+ * Quotes skip the shared fact/topic/person machinery entirely: their
+ * embedding is derived from `text` (not name+description, so
+ * computeDataItemEmbedding doesn't apply), they have no `last_updated`
+ * field to stamp, and — per design — this is their ONLY correction path;
+ * there is no createQuoteEntity/removeQuoteEntity to pair it with.
+ */
+async function updateQuoteEntity(id: string, body: unknown): Promise<Quote> {
+  let input: unknown = body;
+  if (body && typeof body === "object") {
+    const stripped: Record<string, unknown> = { ...body };
+    for (const field of ROUND_TRIP_FIELDS) delete stripped[field];
+    input = stripped;
+  }
+  const result = quoteSchema.safeParse(input);
+  if (!result.success) {
+    throw new CorrectionValidationError(
+      `Invalid quote: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  const state = await loadLatestState();
+  if (!state) {
+    throw new Error("No saved state found. Is EI_DATA_PATH set correctly?");
+  }
+  if (!state.human.quotes.some((q) => q.id === id)) {
+    throw new Error(`No quote found with id: ${id}`);
+  }
+  // Beta's review (I1): the schema above only checks data_item_ids is an
+  // array of strings, not that each string resolves to a real link target.
+  // Without this, a typo'd or stale ID in an external quote repoint — the
+  // primary consumer is the person-split/merge repair workflow — would
+  // silently store a dangling link instead of failing loudly.
+  const validLinkIds = new Set([
+    ...state.human.facts.map((f) => f.id),
+    ...state.human.topics.map((t) => t.id),
+    ...state.human.people.map((p) => p.id),
+  ]);
+  const invalidIds = result.data.data_item_ids.filter((itemId) => !validLinkIds.has(itemId));
+  if (invalidIds.length > 0) {
+    throw new CorrectionValidationError(
+      `Invalid quote: data_item_ids references unknown or disallowed entities: ${invalidIds.join(", ")} (must resolve to an existing fact, topic, or person — not a quote, persona, or unmatched ID)`
+    );
+  }
+  const record: Quote = { ...result.data, id };
+  record.embedding = await computeQuoteEmbedding(record.text);
+  const correction: CorrectionRecord = { op: "upsert", entity_type: "quote", id, record, timestamp: new Date().toISOString() };
+  await writeCorrection(correction);
+  return stripEmbedding(record);
+}
+
+export async function removeEntity(entityType: CorrectableType, id: string): Promise<void> {
+  const state = await loadLatestState();
+  if (!state) {
+    throw new Error("No saved state found. Is EI_DATA_PATH set correctly?");
+  }
+
+  const array = entityType === "fact" ? state.human.facts : entityType === "topic" ? state.human.topics : state.human.people;
+  if (!array.some((item: { id: string }) => item.id === id)) {
+    throw new Error(`No ${entityType} found with id: ${id}`);
+  }
+
+  const correction: CorrectionRecord = { op: "remove", entity_type: entityType, id, timestamp: new Date().toISOString() };
+  await writeCorrection(correction);
+}

package/src/cli/corrections-writer.ts

@@ -0,0 +1,138 @@
+/**
+ * CLI-side write path for ei_update / ei_create / ei_remove.
+ *
+ * Every correction is appended to corrections.json under lock. If a live
+ * Ei instance (TUI or future daemon, #76) holds ei.lock, that's the only
+ * thing this module does — the running Processor drains corrections.json
+ * on its own runLoop tick (~100ms).
+ *
+ * If no live instance holds the lock, this module self-drains directly
+ * into state.json instead of leaving the correction to wait indefinitely
+ * for a TUI session that may not start for days. This is safe specifically
+ * because "no live instance" means nothing holds an in-memory StateManager
+ * that could later overwrite the write with a stale copy — the hazard
+ * corrections.json exists to avoid only applies while an instance is live.
+ *
+ * Sync users are a distinct case from "no state.json": on clean TUI exit,
+ * state.json is renamed to state.backup.json and pushed to the remote
+ * store (see moveToBackup() in tui/src/storage/file.ts and the ceremony
+ * around RemoteSync). A missing state.json with a present state.backup.json
+ * is NOT an error — it means the next TUI launch will pull remote state
+ * fresh, and self-draining into a hand-rolled state.json here would create
+ * a conflicting local state the next launch has to reconcile. In that case
+ * the correction queues in corrections.json and waits for the next TUI
+ * session, same as if a live instance's runLoop just hadn't ticked yet.
+ */
+
+import { join } from "path";
+import { readFile, access } from "fs/promises";
+import { getDataPath } from "./retrieval.js";
+import { withLock, atomicWrite } from "../storage/file-lock.js";
+import { appendCorrection, readCorrections, applyCorrectionsToState } from "../core/corrections.js";
+import type { CorrectionRecord } from "../core/corrections.js";
+import { encodeAllEmbeddings, decodeAllEmbeddings } from "../storage/embeddings.js";
+import type { StorageState } from "../core/types.js";
+
+const STATE_FILE = "state.json";
+const BACKUP_FILE = "state.backup.json";
+const LOCK_FILE = "ei.lock";
+const CORRECTIONS_FILE = "corrections.json";
+
+export function getCorrectionsPath(): string {
+  return join(getDataPath(), CORRECTIONS_FILE);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True if a live Ei instance (TUI or daemon) currently holds ei.lock. */
+async function isLiveInstanceRunning(): Promise<boolean> {
+  const lockPath = join(getDataPath(), LOCK_FILE);
+  let lockText: string;
+  try {
+    lockText = await readFile(lockPath, "utf-8");
+  } catch {
+    return false;
+  }
+  let lock: { pid: number };
+  try {
+    lock = JSON.parse(lockText) as { pid: number };
+  } catch {
+    return false;
+  }
+  try {
+    process.kill(lock.pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Apply a correction. Appends to corrections.json for a live-drained
+ * pickup, or self-drains straight into state.json when nothing is running
+ * to pick it up. Throws if neither state.json nor state.backup.json exist
+ * (no Ei data at this EI_DATA_PATH — misconfiguration, not a sync gap).
+ */
+export async function writeCorrection(record: CorrectionRecord): Promise<void> {
+  const dataPath = getDataPath();
+  const correctionsPath = join(dataPath, CORRECTIONS_FILE);
+
+  if (await isLiveInstanceRunning()) {
+    await appendCorrection(correctionsPath, record);
+    return;
+  }
+
+  const statePath = join(dataPath, STATE_FILE);
+  const stateExists = await pathExists(statePath);
+
+  if (!stateExists) {
+    const backupExists = await pathExists(join(dataPath, BACKUP_FILE));
+    if (!backupExists) {
+      throw new Error(`No Ei data found at ${dataPath}. Is EI_DATA_PATH set correctly?`);
+    }
+    // Sync user, TUI currently closed — state.json will reappear on next
+    // TUI launch (pulled from remote). Queue for that drain instead of
+    // fabricating a local state.json that would conflict with the pull.
+    await appendCorrection(correctionsPath, record);
+    return;
+  }
+
+  // No live instance and state.json exists — safe to self-drain directly.
+  // Re-check liveness after acquiring the lock to shrink the race window
+  // where a TUI/daemon starts between the check above and the write below.
+  await withLock(statePath, async () => {
+    if (await isLiveInstanceRunning()) {
+      await appendCorrection(correctionsPath, record);
+      return;
+    }
+
+    // Read pending corrections, apply them (plus the new record), and clear
+    // the queue — all under correctionsPath's own lock, not just statePath's.
+    // Locking only statePath here left a window where a concurrent
+    // appendCorrection() (which locks correctionsPath, not statePath) could
+    // write a new record between our unlocked read and our unconditional
+    // "[]" clear, silently discarding it. Nesting the correctionsPath lock
+    // inside statePath's serializes against every other writer of that file.
+    await withLock(correctionsPath, async () => {
+      const text = await readFile(statePath, "utf-8");
+      const state = decodeAllEmbeddings(JSON.parse(text) as StorageState);
+
+      const pending = await readCorrections(correctionsPath);
+      applyCorrectionsToState(state, [...pending, record]);
+      state.timestamp = new Date().toISOString();
+
+      // State write happens before the queue clear: if we crash in between,
+      // the next run still sees the pending records in corrections.json and
+      // safely re-applies them (upsert/remove are idempotent by id).
+      await atomicWrite(statePath, JSON.stringify(encodeAllEmbeddings(state), null, 2));
+      await atomicWrite(correctionsPath, "[]");
+    });
+  });
+}