ei-tui 1.6.9 → 1.7.0

package/src/cli.ts

@@ -17,6 +17,9 @@ import type { StorageState } from "./core/types";
 import { resolvePersonaId, filterByPersona, filterTypeSpecificByPersona, filterBySource, filterTypeSpecificBySource } from "./cli/persona-filter.js";
 import { installMcpClients } from "./cli/install.js";
 import { getRecentSessionMessages } from "./cli/session-context.js";
+import { createEntity, updateEntity, removeEntity, CorrectionValidationError, CORRECTABLE_TYPES, UPDATABLE_TYPES } from "./cli/corrections-endpoints.js";
+import { createPersonaEntity, updatePersonaEntity, removePersonaEntity } from "./cli/persona-corrections.js";
+import type { CorrectableType } from "./core/corrections.js";
 import pkg from "../package.json" assert { type: "json" };
 
 const rawArgs = process.argv.slice(2);
@@ -38,6 +41,39 @@ const TYPE_ALIASES: Record<string, string> = {
   personas: "personas",
 };
 
+// Wider set accepted by `ei create/update/remove persona` — corrections-endpoints.ts's
+// CORRECTABLE_TYPES/UPDATABLE_TYPES intentionally stay persona-free (personas bypass
+// that module's shared SCHEMAS dispatch entirely, see persona-corrections.ts), so this
+// CLI-only layer is what actually widens the accepted type set.
+const CLI_CORRECTABLE_TYPES = [...CORRECTABLE_TYPES, "persona"] as const;
+const CLI_UPDATABLE_TYPES = [...UPDATABLE_TYPES, "persona"] as const;
+
+// Singular CorrectableType resolution for `ei create/update/remove` — derived
+// from TYPE_ALIASES + CLI_CORRECTABLE_TYPES so the two alias systems can never
+// silently diverge on which strings are accepted (e.g. "person"/"people"
+// stay synonymous here too, since both funnel through TYPE_ALIASES first).
+const PLURAL_TO_CORRECTABLE: Record<string, CorrectableType> = Object.fromEntries(
+  CLI_CORRECTABLE_TYPES.map((t) => [TYPE_ALIASES[t], t])
+);
+
+function resolveCorrectableType(raw: string): CorrectableType | null {
+  const plural = TYPE_ALIASES[raw];
+  return plural ? PLURAL_TO_CORRECTABLE[plural] ?? null : null;
+}
+
+// Plural CorrectableType resolution for `ei update` — same TYPE_ALIASES
+// lookup as resolveCorrectableType above, but sourced from CLI_UPDATABLE_TYPES
+// instead of CLI_CORRECTABLE_TYPES since quotes are correctable via update
+// (repointing data_item_ids after a split/merge, fixing mistranscribed
+// text) but never created or removed.
+const PLURAL_TO_UPDATABLE: Record<string, CorrectableType> = Object.fromEntries(
+  CLI_UPDATABLE_TYPES.map((t) => [TYPE_ALIASES[t], t])
+);
+function resolveUpdatableType(raw: string): CorrectableType | null {
+  const plural = TYPE_ALIASES[raw];
+  return plural ? PLURAL_TO_UPDATABLE[plural] ?? null : null;
+}
+
 function printHelp(): void {
   console.log(`
 Ei
@@ -55,6 +91,9 @@ Usage:
   ei --id <id>                  Look up a specific entity by ID
   echo <id> | ei --id           Look up entity by ID from stdin
   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 (full record, not a patch; fact/topic/person/quote/persona)
+  ei remove <type> <id>         Remove an entity by ID (fact/topic/person/persona; not quotes)
 
 Types:
   quote / quotes      Quotes from conversation history
@@ -69,12 +108,13 @@ Options:
   --persona, -p       Filter to entities a specific persona has learned about
   --source, -s        Filter to entities from a specific source (prefix match, e.g. "cursor", "codex:my-machine", "opencode:my-machine:ses_abc123")
   --id                Look up entity by ID (accepts value or stdin)
-  --install           Register Ei with Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks where supported)
+  --install           Register Ei with Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks + skills where supported)
   --sync              Pull latest state from remote sync server into state.backup.json (no TUI required)
   --session <id>      Session ID to enrich the query with recent context (use with --hook-source)
   --hook-source <src> Source of the hook: "opencode-plugin" (OpenCode SQLite), "cursor", or "codex"
   --transcript <path> Path to a Claude Code JSONL transcript file for context enrichment
   --help, -h          Show this help message
+  --json <json>       JSON body for create/update (full record for update, not a patch)
 
 Examples:
   ei "debugging"                         # Search everything
@@ -86,6 +126,13 @@ Examples:
   ei topics --source cursor "X"          # Topics learned from Cursor sessions
   ei --id abc-123                        # Look up entity by ID
   ei "memory leak" | jq .[0].id | ei --id  # Pipe ID from search
+  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                 # Remove a fact by ID
 `);
 }
 
@@ -146,6 +193,89 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  if (args[0] === "create") {
+    const rawType = args[1];
+    const entityType = rawType ? resolveCorrectableType(rawType) : null;
+    if (!entityType) {
+      console.error(`ei create requires a valid type (${CLI_CORRECTABLE_TYPES.join(", ")}). Got: ${rawType ?? "(none)"}`);
+      process.exit(1);
+    }
+    const jsonIdx = args.indexOf("--json");
+    const jsonStr = jsonIdx !== -1 ? args[jsonIdx + 1] : undefined;
+    if (!jsonStr) {
+      console.error("ei create requires --json '<json>'");
+      process.exit(1);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`Invalid JSON: ${(e as Error).message}`);
+      process.exit(1);
+    }
+    try {
+      const result = entityType === "persona" ? await createPersonaEntity(body) : await createEntity(entityType, body);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(e instanceof CorrectionValidationError ? e.message : (e as Error).message);
+      process.exit(1);
+    }
+  }
+
+  if (args[0] === "update") {
+    const rawType = args[1];
+    const id = args[2];
+    const entityType = rawType ? resolveUpdatableType(rawType) : null;
+    if (!entityType || !id) {
+      console.error(`Usage: ei update <type> <id> --json '<json>' (types: ${CLI_UPDATABLE_TYPES.join(", ")})`);
+      process.exit(1);
+    }
+    const jsonIdx = args.indexOf("--json");
+    const jsonStr = jsonIdx !== -1 ? args[jsonIdx + 1] : undefined;
+    if (!jsonStr) {
+      console.error("ei update requires --json '<json>'");
+      process.exit(1);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`Invalid JSON: ${(e as Error).message}`);
+      process.exit(1);
+    }
+    try {
+      const record = entityType === "persona" ? await updatePersonaEntity(id, body) : await updateEntity(entityType, id, body);
+      console.log(JSON.stringify(record, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(e instanceof CorrectionValidationError ? e.message : (e as Error).message);
+      process.exit(1);
+    }
+  }
+
+  if (args[0] === "remove") {
+    const rawType = args[1];
+    const id = args[2];
+    const entityType = rawType ? resolveCorrectableType(rawType) : null;
+    if (!entityType || !id) {
+      console.error(`Usage: ei remove <type> <id> (types: ${CLI_CORRECTABLE_TYPES.join(", ")})`);
+      process.exit(1);
+    }
+    try {
+      if (entityType === "persona") {
+        await removePersonaEntity(id);
+      } else {
+        await removeEntity(entityType, id);
+      }
+      console.log(JSON.stringify({ removed: true, id }, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error((e as Error).message);
+      process.exit(1);
+    }
+  }
+
   if (args[0] === "--sync") {
     const { getDataPath } = await import("./cli/retrieval.js");
     const { RemoteSync } = await import("./storage/remote.js");

package/src/core/corrections.ts

@@ -0,0 +1,233 @@
+/**
+ * Corrections Queue — external write path for CLI/MCP tools.
+ *
+ * Ei's CLI and MCP server are read-only against a snapshot of state.json —
+ * they never hold the live StateManager the running TUI/daemon owns, so
+ * they can't safely mutate state.json directly (the running instance's
+ * next debounced save would silently clobber the write with its stale
+ * in-memory copy).
+ *
+ * corrections.json is the queue that closes this gap. External writers
+ * (ei_update / ei_create / ei_remove) append fully-formed CorrectionRecords
+ * here under an advisory lock. Two consumers drain it:
+ *   - The running Processor, once per runLoop tick (near-instant, ~100ms).
+ *   - The CLI itself, self-draining directly into state.json when it
+ *     detects no live instance is running (see src/cli/corrections-io.ts).
+ *
+ * Every CorrectionRecord is a complete, ready-to-apply entity — including
+ * a pre-computed embedding and (for creates) a pre-assigned id — so
+ * draining is a pure apply, never a fetch-then-merge.
+ */
+
+import type { HumanEntity, Fact, Topic, Person, Quote, PersonaEntity, StorageState } from "./types.js";
+import { isReservedPersonaId } from "./types.js";
+import { withLock, atomicWrite } from "../storage/file-lock.js";
+
+export type CorrectableType = "fact" | "topic" | "person" | "quote" | "persona";
+export type CorrectableEntity = Fact | Topic | Person | Quote | PersonaEntity;
+export const CORRECTABLE_TYPES: CorrectableType[] = ["fact", "topic", "person", "quote", "persona"];
+
+export interface CorrectionUpsert {
+  op: "upsert";
+  entity_type: CorrectableType;
+  id: string;
+  record: CorrectableEntity;
+  timestamp: string;
+}
+
+export interface CorrectionRemove {
+  op: "remove";
+  entity_type: CorrectableType;
+  id: string;
+  timestamp: string;
+}
+
+export type CorrectionRecord = CorrectionUpsert | CorrectionRemove;
+
+/**
+ * Runtime shape validation for a CorrectionRecord read back from
+ * corrections.json. The TypeScript union is compile-time only — every
+ * record actually enters the system via `JSON.parse(...) as CorrectionRecord`
+ * in readCorrections(), so a malformed-but-valid-JSON record (bad `op`,
+ * mismatched `record.id`, missing `record` on an upsert) is otherwise
+ * silently trusted. Both consumers (CLI read-merge/self-drain via
+ * applyCorrectionToHuman, and Processor.applyCorrectionRecord) call this
+ * before mutating anything — it throws, never coerces, so a malformed `op`
+ * can never be silently treated as its sibling operation.
+ */
+export function assertValidCorrection(value: unknown): asserts value is CorrectionRecord {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Malformed correction record: expected an object, got ${JSON.stringify(value)}`);
+  }
+  if (!("op" in value) || (value.op !== "upsert" && value.op !== "remove")) {
+    throw new Error(`Malformed correction record: op must be "upsert" or "remove", got ${JSON.stringify("op" in value ? value.op : undefined)}`);
+  }
+  if (!("entity_type" in value) || !CORRECTABLE_TYPES.includes(value.entity_type as CorrectableType)) {
+    throw new Error(`Malformed correction record: entity_type must be one of ${CORRECTABLE_TYPES.join(", ")}, got ${JSON.stringify("entity_type" in value ? value.entity_type : undefined)}`);
+  }
+  if (!("id" in value) || typeof value.id !== "string" || value.id.length === 0) {
+    throw new Error(`Malformed correction record: id must be a non-empty string, got ${JSON.stringify("id" in value ? value.id : undefined)}`);
+  }
+  if (value.op === "upsert") {
+    if (!("record" in value) || !value.record || typeof value.record !== "object") {
+      throw new Error(`Malformed correction record: upsert requires a record object`);
+    }
+    if (!("id" in value.record) || value.record.id !== value.id) {
+      throw new Error(`Malformed correction record: record.id (${JSON.stringify("id" in value.record ? value.record.id : undefined)}) must equal wrapper id (${JSON.stringify(value.id)})`);
+    }
+  }
+}
+
+/**
+ * Read pending corrections without a lock. Returns [] if the file doesn't
+ * exist or is empty. fs/promises is imported dynamically, not statically —
+ * this module is transitively bundled into Web's browser build via
+ * src/core/processor.ts, and a static `import { readFile } from "fs/promises"`
+ * fails Vite's rollup build (no named exports on the browser-externalized
+ * stub), not just at runtime.
+ */
+export async function readCorrections(correctionsPath: string): Promise<CorrectionRecord[]> {
+  const { readFile } = await import(/* @vite-ignore */ "fs/promises");
+  let text: string;
+  try {
+    text = await readFile(correctionsPath, "utf-8");
+  } catch {
+    return [];
+  }
+  if (!text) return [];
+  return JSON.parse(text) as CorrectionRecord[];
+}
+
+/**
+ * Append one correction under lock (read-modify-write — corrections.json
+ * is a JSON array, not an append-only log, so concurrent writers must
+ * serialize through the same lock rather than racing on a blind append).
+ */
+export async function appendCorrection(
+  correctionsPath: string,
+  record: CorrectionRecord
+): Promise<void> {
+  await withLock(correctionsPath, async () => {
+    const existing = await readCorrections(correctionsPath);
+    existing.push(record);
+    await atomicWrite(correctionsPath, JSON.stringify(existing, null, 2));
+  });
+}
+
+/**
+ * Merge a person's `name` from its primary identifier, replicating the
+ * invariant HumanState.person_upsert enforces on the live-write path
+ * (CONTRACTS.md "Person Identifiers — name Sync Rule"). Both consumers of
+ * this module (Live's StateManager and the CLI's self-drain) must produce
+ * an identical HumanEntity for a given corrections.json, so the formula
+ * is centralized here rather than re-derived at each call site.
+ */
+function syncPersonName(person: Person): Person {
+  const identifiers = person.identifiers ?? [];
+  const primary = identifiers.find((i) => i.is_primary) ?? identifiers[0];
+  return primary ? { ...person, name: primary.value } : person;
+}
+
+/**
+ * Resolve the target array for a CorrectableType. Throws on anything
+ * other than the 4 known types — corrections.json is external input from
+ * CLI/MCP tools (potentially LLM-driven), and a malformed entity_type must
+ * never silently fall through to the people array. Live's Processor
+ * already enforces this (applyCorrectionRecord); this is the equivalent
+ * guard for the CLI read-merge and self-drain paths.
+ */
+function getCorrectableArray(human: HumanEntity, entityType: string): Array<{ id: string }> {
+  if (entityType === "fact") return human.facts;
+  if (entityType === "topic") return human.topics;
+  if (entityType === "person") return human.people;
+  if (entityType === "quote") return human.quotes;
+  throw new Error(`Unrecognized correction entity_type: ${entityType}`);
+}
+
+/**
+ * Apply one correction to a HumanEntity in place, mirroring the exact
+ * upsert/remove semantics of HumanState (src/core/state/human.ts) —
+ * replace-by-id for upsert, splice + orphaned quote-reference cleanup for
+ * remove (for all 3 types, matching fact_remove/topic_remove/person_remove
+ * in HumanState — not just person). Used by both the CLI's read-merge
+ * (materializing a corrected view without a StateManager) and its
+ * self-drain (writing corrections straight into state.json when no live
+ * instance is running).
+ */
+export function applyCorrectionToHuman(human: HumanEntity, correction: CorrectionRecord): void {
+  assertValidCorrection(correction);
+  const array = getCorrectableArray(human, correction.entity_type);
+
+  if (correction.op === "remove") {
+    const idx = array.findIndex((item) => item.id === correction.id);
+    if (idx < 0) return;
+    array.splice(idx, 1);
+    human.quotes.forEach((q) => {
+      q.data_item_ids = q.data_item_ids.filter((itemId) => itemId !== correction.id);
+    });
+    human.last_updated = new Date().toISOString();
+    return;
+  }
+
+  const record = correction.entity_type === "person"
+    ? syncPersonName(correction.record as Person)
+    : correction.record;
+  const idx = array.findIndex((item) => item.id === correction.id);
+  if (idx >= 0) {
+    array[idx] = record;
+  } else {
+    array.push(record);
+  }
+  human.last_updated = new Date().toISOString();
+}
+
+/** Apply every pending correction to a HumanEntity, in file order (later records for the same id win). */
+export function applyCorrectionsToHuman(human: HumanEntity, corrections: CorrectionRecord[]): void {
+  for (const correction of corrections) {
+    applyCorrectionToHuman(human, correction);
+  }
+}
+
+/**
+ * Apply one correction to a StorageState's personas map in place. Personas
+ * live outside HumanEntity — src/core/types/integrations.ts's StorageState.personas
+ * is a top-level `Record<id, {entity, messages}>` — so they need their own
+ * apply function rather than routing through getCorrectableArray/
+ * applyCorrectionToHuman, which only ever resolve arrays on HumanEntity.
+ *
+ * The reserved-persona delete guard here is defense-in-depth for a
+ * hand-edited corrections.json: the primary guard is the SYNCHRONOUS check
+ * in src/cli/persona-corrections.ts's removePersonaEntity, which runs
+ * before a correction is ever queued (so a live-drained rejection here can
+ * never surface as a silent no-op after an apparent CLI success).
+ */
+export function applyCorrectionToPersonas(personas: StorageState["personas"], correction: CorrectionRecord): void {
+  assertValidCorrection(correction);
+  if (correction.op === "remove") {
+    if (isReservedPersonaId(correction.id)) {
+      throw new Error(`Cannot delete reserved persona "${correction.id}". Use archive instead.`);
+    }
+    delete personas[correction.id];
+    return;
+  }
+  personas[correction.id] = {
+    entity: correction.record as PersonaEntity,
+    messages: personas[correction.id]?.messages ?? [],
+  };
+}
+
+/** Route one correction to its target: the personas map for entity_type "persona", the HumanEntity for everything else. */
+export function applyCorrectionToState(state: StorageState, correction: CorrectionRecord): void {
+  if (correction.entity_type === "persona") {
+    applyCorrectionToPersonas(state.personas, correction);
+  } else {
+    applyCorrectionToHuman(state.human, correction);
+  }
+}
+
+/** Apply every pending correction to a StorageState, in file order (later records for the same id win). */
+export function applyCorrectionsToState(state: StorageState, corrections: CorrectionRecord[]): void {
+  for (const correction of corrections) {
+    applyCorrectionToState(state, correction);
+  }
+}

package/src/core/handlers/human-matching.ts

@@ -282,7 +282,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
         value: i.value,
         ...(i.is_primary ? { is_primary: i.is_primary } : {}),
       })),
-      state
+      state.persona_getAll()
     );
     const allCandidateIds = [...llmIdentifiers, ...candidateIdentifiers];
     if (allCandidateIds.length === 0) {
@@ -303,7 +303,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
         ...i,
         type: normalizeIdentifierType(i.type, state),
       })),
-      state
+      state.persona_getAll()
     );
     for (const id of sanitizedToAdd) {
       if (!base.some(e => e.value === id.value)) {

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();