@rubytech/create-realagent 1.0.832 → 1.0.834

package/payload/platform/lib/admins-write/src/index.ts

@@ -0,0 +1,311 @@
+// admins-write — single chokepoint for the dual-file admin write
+// (users.json device-level PIN auth + account.json account-level role).
+//
+// Task 904 background: pre-Task-904 the two writers — `admin-add`
+// (platform/plugins/admin/mcp/src/index.ts) and `set-pin` POST
+// (platform/ui/server/routes/onboarding.ts) — each performed the dual write
+// inline. They drifted: admin-add returned `is_error: true` with a per-leg
+// `[admin-auth-store]` line on partial failure; set-pin logged on stderr but
+// otherwise rolled forward. This module collapses both into one routed write
+// so the static check `grep -rnE 'admins\.push|config\.admins\s*=' platform/`
+// returns 0 outside this file (excluding tests, scripts, and the reader paths
+// which never push).
+//
+// Atomicity contract — single file: write-temp + rename, durable.
+// Atomicity contract — across files: NOT atomic. POSIX has no two-file
+// transaction. The helper writes users.json first, then account.json. On
+// account.json failure with users.json already written, the result names the
+// partial state. Callers MUST surface partial state to the operator (admin-add
+// returns is_error: true with the [admins-write] line; set-pin returns 500
+// with the same). Same trust model as Task 850's [admin-auth-store] pair.
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface UserEntry {
+  userId: string;
+  pin: string; // SHA-256 hash
+  // Deprecated `name` field (Task 829) — preserved for legacy entries until
+  // session.ts strips it. Never written by this helper.
+  name?: string;
+}
+
+export interface AdminEntry {
+  userId: string;
+  role: "owner" | "admin";
+}
+
+export interface AdminWriteInput {
+  userId: string;
+  pin: string;          // SHA-256 hash
+  role: "owner" | "admin";
+  usersFile: string;    // absolute path to users.json
+  accountDir: string;   // absolute path to account dir (containing account.json)
+  caller: string;       // identifier for the [admins-write] log line
+}
+
+export interface AdminWriteResult {
+  usersJsonResult: "ok" | "fail" | "noop";
+  accountJsonResult: "ok" | "fail" | "noop";
+  usersError?: string;
+  accountError?: string;
+}
+
+function logLine(input: AdminWriteInput, result: AdminWriteResult): void {
+  const userIdShort = input.userId.slice(0, 8);
+  console.error(
+    `[admins-write] caller=${input.caller} userId=${userIdShort} ` +
+      `usersJsonResult=${result.usersJsonResult} accountJsonResult=${result.accountJsonResult}` +
+      (result.usersError ? ` usersError=${result.usersError}` : "") +
+      (result.accountError ? ` accountError=${result.accountError}` : ""),
+  );
+}
+
+function writeFileAtomic(filePath: string, contents: string, mode?: number): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tempPath, contents, mode !== undefined ? { mode } : undefined);
+  renameSync(tempPath, filePath);
+}
+
+/**
+ * Write a single admin entry across both auth stores (users.json + account.json admins[]).
+ *
+ * Idempotent on userId: if the userId already exists in users.json, the PIN
+ * field is updated in place rather than duplicated; admins[] is checked for
+ * presence before pushing.
+ *
+ * Always emits exactly one `[admins-write] caller=… userId=<prefix> usersJsonResult=… accountJsonResult=…`
+ * line — success and failure paths both fire it. Operators grep for this single
+ * predicate when reconstructing a partial-write incident.
+ */
+export function writeAdminEntry(input: AdminWriteInput): AdminWriteResult {
+  const result: AdminWriteResult = { usersJsonResult: "noop", accountJsonResult: "noop" };
+
+  // 1. users.json — read-modify-write atomically.
+  try {
+    let users: UserEntry[] = [];
+    if (existsSync(input.usersFile)) {
+      const raw = readFileSync(input.usersFile, "utf-8").trim();
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+          throw new Error("users.json is not an array");
+        }
+        users = parsed as UserEntry[];
+      }
+    }
+
+    const existing = users.findIndex(u => u.userId === input.userId);
+    if (existing === -1) {
+      users.push({ userId: input.userId, pin: input.pin });
+    } else {
+      // Preserve any sibling fields that other writers may have set, but
+      // overwrite pin. Strip the deprecated `name` field on touch (Task 829).
+      const merged: UserEntry = { ...users[existing], pin: input.pin };
+      delete merged.name;
+      users[existing] = merged;
+    }
+
+    writeFileAtomic(input.usersFile, JSON.stringify(users, null, 2) + "\n", 0o600);
+    result.usersJsonResult = "ok";
+  } catch (err) {
+    result.usersJsonResult = "fail";
+    result.usersError = err instanceof Error ? err.message : String(err);
+    logLine(input, result);
+    return result;
+  }
+
+  // 2. account.json — read-modify-write atomically.
+  try {
+    const accountJsonPath = join(input.accountDir, "account.json");
+    if (!existsSync(accountJsonPath)) {
+      throw new Error(`account.json not found at ${accountJsonPath}`);
+    }
+    const config = JSON.parse(readFileSync(accountJsonPath, "utf-8")) as Record<string, unknown>;
+    const admins = (config.admins ?? []) as AdminEntry[];
+    if (admins.some(a => a.userId === input.userId)) {
+      result.accountJsonResult = "noop";
+    } else {
+      admins.push({ userId: input.userId, role: input.role });
+      config.admins = admins;
+      writeFileAtomic(accountJsonPath, JSON.stringify(config, null, 2) + "\n");
+      result.accountJsonResult = "ok";
+    }
+  } catch (err) {
+    result.accountJsonResult = "fail";
+    result.accountError = err instanceof Error ? err.message : String(err);
+  }
+
+  logLine(input, result);
+  return result;
+}
+
+export interface AdminRemoveInput {
+  userId: string;
+  accountDir: string;
+  caller: string;
+}
+
+export interface AdminRemoveResult {
+  accountJsonResult: "ok" | "fail" | "noop";
+  accountError?: string;
+}
+
+/**
+ * Remove a single admin entry from account.json admins[] — does NOT touch
+ * users.json (the device-level entry is preserved because the user may admin
+ * other accounts). Single-file operation; the [admins-write] line records
+ * `usersJsonResult=skip` so the grep-by-helper-call still picks it up.
+ */
+export function removeAdminFromAccount(input: AdminRemoveInput): AdminRemoveResult {
+  const result: AdminRemoveResult = { accountJsonResult: "noop" };
+  const userIdShort = input.userId.slice(0, 8);
+
+  try {
+    const accountJsonPath = join(input.accountDir, "account.json");
+    if (!existsSync(accountJsonPath)) {
+      throw new Error(`account.json not found at ${accountJsonPath}`);
+    }
+    const config = JSON.parse(readFileSync(accountJsonPath, "utf-8")) as Record<string, unknown>;
+    const admins = (config.admins ?? []) as AdminEntry[];
+    const targetIndex = admins.findIndex(a => a.userId === input.userId);
+    if (targetIndex === -1) {
+      result.accountJsonResult = "noop";
+    } else {
+      admins.splice(targetIndex, 1);
+      config.admins = admins;
+      writeFileAtomic(accountJsonPath, JSON.stringify(config, null, 2) + "\n");
+      result.accountJsonResult = "ok";
+    }
+  } catch (err) {
+    result.accountJsonResult = "fail";
+    result.accountError = err instanceof Error ? err.message : String(err);
+  }
+
+  console.error(
+    `[admins-write] caller=${input.caller} userId=${userIdShort} ` +
+      `usersJsonResult=skip accountJsonResult=${result.accountJsonResult}` +
+      (result.accountError ? ` accountError=${result.accountError}` : ""),
+  );
+  return result;
+}
+
+export interface InvariantCheckInput {
+  /** Absolute path to users.json (persistent location). */
+  usersFile: string;
+  /** Absolute path to the accounts root (e.g. <INSTALL_DIR>/data/accounts). */
+  accountsDir: string;
+  /** Tag for the log prefix — `install-invariant` or `admin-invariant`. */
+  tag: "install-invariant" | "admin-invariant";
+}
+
+export interface InvariantCheckResult {
+  divergences: number;
+  /** Userids in account.json admins[] that have no row in users.json. */
+  accountWithoutUsers: Array<{ userId: string; source: string }>;
+  /** Userids in users.json that no account.json admins[] references. */
+  usersWithoutAccount: Array<{ userId: string }>;
+}
+
+/**
+ * Walk every account.json under accountsDir and compare its admins[] to
+ * users.json. Emits one log line per divergence and one summary line.
+ *
+ * Behaviour: log-only — does NOT throw, does NOT refuse boot or install.
+ * Pre-Task-904 installs that already diverged would otherwise brick on the
+ * first boot of a Task-904 device. The summary line `divergences=<n>` is
+ * always emitted (wired-up assertion); per-divergence lines fire only when
+ * divergences > 0. Operators grep `[install-invariant]` or `[admin-invariant]`
+ * to detect the regression class without reading every install log.
+ *
+ * Promotion to refuse-or-degrade is a future sprint; capture as a TODO once
+ * the deployed fleet has been audited clean.
+ */
+export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCheckResult {
+  const result: InvariantCheckResult = {
+    divergences: 0,
+    accountWithoutUsers: [],
+    usersWithoutAccount: [],
+  };
+
+  // Read users.json userIds (persistent file). Absent file == empty set; do
+  // not abort — first-boot before set-pin has run is a legitimate state.
+  const usersUserIds = new Set<string>();
+  if (existsSync(input.usersFile)) {
+    try {
+      const raw = readFileSync(input.usersFile, "utf-8").trim();
+      if (raw) {
+        const users = JSON.parse(raw) as UserEntry[];
+        for (const u of users) {
+          if (typeof u.userId === "string") usersUserIds.add(u.userId);
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[${input.tag}] users.json unreadable usersFile=${input.usersFile} error=${msg}`);
+    }
+  }
+
+  // Walk account dirs. Skip dotfiles (.trash/) and missing account.json.
+  const accountUserIds = new Set<string>();
+  if (existsSync(input.accountsDir)) {
+    let entries: string[];
+    try {
+      entries = readdirSync(input.accountsDir);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[${input.tag}] accounts-dir unreadable accountsDir=${input.accountsDir} error=${msg}`);
+      console.error(`[${input.tag}] check complete divergences=0 (accounts-dir unreadable)`);
+      return result;
+    }
+
+    for (const entry of entries) {
+      if (entry.startsWith(".")) continue;
+      const accountDir = join(input.accountsDir, entry);
+      try {
+        if (!statSync(accountDir).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      const accountJsonPath = join(accountDir, "account.json");
+      if (!existsSync(accountJsonPath)) continue;
+      let admins: AdminEntry[] = [];
+      try {
+        const config = JSON.parse(readFileSync(accountJsonPath, "utf-8")) as Record<string, unknown>;
+        admins = (config.admins ?? []) as AdminEntry[];
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[${input.tag}] account.json unreadable source=${accountJsonPath} error=${msg}`);
+        continue;
+      }
+
+      for (const a of admins) {
+        if (typeof a.userId !== "string") continue;
+        accountUserIds.add(a.userId);
+        if (!usersUserIds.has(a.userId)) {
+          const userIdShort = a.userId.slice(0, 8);
+          console.error(
+            `[${input.tag}] direction=account-without-users userId=${userIdShort} source=${accountJsonPath}`,
+          );
+          result.accountWithoutUsers.push({ userId: a.userId, source: accountJsonPath });
+          result.divergences += 1;
+        }
+      }
+    }
+  }
+
+  for (const uid of usersUserIds) {
+    if (!accountUserIds.has(uid)) {
+      const userIdShort = uid.slice(0, 8);
+      console.error(
+        `[${input.tag}] direction=users-without-account userId=${userIdShort} source=${input.usersFile}`,
+      );
+      result.usersWithoutAccount.push({ userId: uid });
+      result.divergences += 1;
+    }
+  }
+
+  console.error(`[${input.tag}] check complete divergences=${result.divergences}`);
+  return result;
+}

package/payload/platform/lib/admins-write/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/neo4j/migrations/009-conversation-archive-title.ts

@@ -0,0 +1,197 @@
+/**
+ * Migration 009 — Backfill `title` on every legacy `:ConversationArchive`
+ * (Task 902 sub-scope A).
+ *
+ * Pre-902 the bin wrote per-session counter strings ("Session 1/N: K messages,
+ * X chunks") into `:ConversationArchive.summary`. Because the MERGE Cypher
+ * set `summary` ONLY in `ON CREATE SET`, the FIRST per-session call's counter
+ * was frozen for the lifetime of the archive — and the UI's `pickDisplayName`
+ * fell through to `summary` for `:ConversationArchive`, so every archive
+ * rendered as the literal "Session 1/N…" string of its first checkpoint.
+ *
+ * Task 902 added a stable `title` property and a UI branch that prefers it.
+ * This migration backfills `title` on every legacy archive that predates the
+ * new contract, so the UI never label-falls-through:
+ *
+ *   <source> · <owner> ↔ <other1>, <other2>, … · <YYYY-MM-DD>→<YYYY-MM-DD>
+ *
+ * Owner / participant resolution: query `(p)-[:PARTICIPANT_IN]->(a)` for the
+ * archive's participant set, then pick a name per node by label:
+ *   :AdminUser → displayName, then slug
+ *   :Person    → givenName + familyName
+ * Owner is identified by AdminUser presence in the set; other participants
+ * are everyone else. When neither name resolves on a node, fall back to a
+ * short elementId prefix (mirrors the bin's degraded behaviour at
+ * `computeArchiveTitle`, so the live ingest produces the same shape).
+ *
+ * Date range: head and tail `:Section:Conversation` chunks via
+ * `firstMessageAt` / `lastMessageAt` properties (Task 891 chunk schema).
+ * When chunks lack those properties (rare — pre-Task-891 archives), fall
+ * back to the parent's `lastIngestedMessageAt` for both ends. When even
+ * that is missing, the date segment is `?→?`. The migration NEVER leaves
+ * `title` NULL — every row gets a string, even if degraded — so the
+ * verification query `MATCH (a:ConversationArchive) WHERE a.title IS NULL
+ * RETURN count(a)` returns 0 unconditionally.
+ *
+ * Idempotency: only archives where `title IS NULL` are touched. A second
+ * boot finds zero rows and emits `archives-titled=0`.
+ *
+ * Observability:
+ *   `[migration:conversation-archive-title]
+ *      archives-titled=N degraded-no-dates=N degraded-no-names=N`
+ *
+ * REMOVE WHEN: every install we ship has been booted once on a version
+ * ≥ Task 902 AND no live archive carries `title IS NULL`.
+ */
+
+type Neo4jDriverLike = {
+  session(): {
+    run(
+      cypher: string,
+      params?: Record<string, unknown>,
+    ): Promise<{ records: Array<{ get(key: string): unknown }> }>;
+    close(): Promise<void>;
+  };
+};
+
+interface ParticipantRow {
+  elementId: string;
+  labels: string[];
+  displayName?: string;
+  slug?: string;
+  givenName?: string;
+  familyName?: string;
+}
+
+const ISO_DATE_RE = /^(\d{4}-\d{2}-\d{2})/;
+
+function isoToYmd(iso: unknown): string {
+  if (typeof iso !== "string") return "?";
+  const m = iso.match(ISO_DATE_RE);
+  return m ? m[1] : "?";
+}
+
+function pickName(row: ParticipantRow): string {
+  if (row.labels.includes("AdminUser")) {
+    if (row.displayName && row.displayName.trim()) return row.displayName.trim();
+    if (row.slug && row.slug.trim()) return row.slug.trim();
+  }
+  if (row.labels.includes("Person")) {
+    const full = [row.givenName, row.familyName]
+      .filter((s): s is string => typeof s === "string" && s.trim().length > 0)
+      .map((s) => s.trim())
+      .join(" ");
+    if (full) return full;
+  }
+  return row.elementId.slice(0, 8);
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+export async function backfillConversationArchiveTitle(
+  driver: Neo4jDriverLike,
+): Promise<void> {
+  const session = driver.session();
+  let archivesTitled = 0;
+  let degradedNoDates = 0;
+  let degradedNoNames = 0;
+  try {
+    // 1. Find every archive lacking a title. For each, pull the participant
+    //    set + head/tail chunk timestamps in one batch round-trip per archive.
+    //    Idempotent: re-runs return zero rows.
+    const archives = await session.run(
+      `MATCH (a:ConversationArchive)
+       WHERE a.title IS NULL
+       RETURN elementId(a) AS elemId,
+              coalesce(a.source, 'whatsapp') AS source,
+              a.lastIngestedMessageAt AS lastAt`,
+    );
+    for (const rec of archives.records) {
+      const elemId = rec.get("elemId") as string;
+      const source = rec.get("source") as string;
+      const fallbackLastAt = rec.get("lastAt") as string | null;
+
+      // 2. Pull the participant rows.
+      const partRes = await session.run(
+        `MATCH (p)-[:PARTICIPANT_IN]->(a:ConversationArchive)
+         WHERE elementId(a) = $elemId AND (p:Person OR p:AdminUser)
+         RETURN elementId(p) AS elemId, labels(p) AS labels, properties(p) AS props`,
+        { elemId },
+      );
+      const owner: ParticipantRow[] = [];
+      const others: ParticipantRow[] = [];
+      let anyDegraded = false;
+      for (const r of partRes.records) {
+        const labels = (r.get("labels") as string[]) || [];
+        const props = (r.get("props") as Record<string, unknown>) || {};
+        const row: ParticipantRow = {
+          elementId: r.get("elemId") as string,
+          labels,
+          displayName: asString(props.displayName),
+          slug: asString(props.slug),
+          givenName: asString(props.givenName),
+          familyName: asString(props.familyName),
+        };
+        const name = pickName(row);
+        if (name === row.elementId.slice(0, 8)) anyDegraded = true;
+        if (labels.includes("AdminUser")) owner.push(row);
+        else others.push(row);
+      }
+      if (anyDegraded) degradedNoNames += 1;
+      const ownerName = owner.length > 0 ? pickName(owner[0]) : "?";
+      const otherNames = others.length > 0
+        ? others.map((o) => pickName(o)).join(", ")
+        : "?";
+
+      // 3. Pull the head and tail chunk timestamps. Chunks land in NEXT-chain
+      //    order; the chain head has no incoming :NEXT edge inside the
+      //    same archive, the tail has no outgoing :NEXT.
+      const datesRes = await session.run(
+        `MATCH (a:ConversationArchive)-[:HAS_SECTION]->(c:Section:Conversation)
+         WHERE elementId(a) = $elemId
+         WITH c, c.firstMessageAt AS first, c.lastMessageAt AS last
+         RETURN min(first) AS firstAt, max(last) AS lastAt`,
+        { elemId },
+      );
+      let firstAt = asString(datesRes.records[0]?.get("firstAt"));
+      let lastAt = asString(datesRes.records[0]?.get("lastAt"));
+      if (!firstAt || !lastAt) {
+        if (fallbackLastAt) {
+          firstAt = firstAt ?? fallbackLastAt;
+          lastAt = lastAt ?? fallbackLastAt;
+        }
+      }
+      if (!firstAt || !lastAt) {
+        degradedNoDates += 1;
+      }
+      const firstYmd = isoToYmd(firstAt);
+      const lastYmd = isoToYmd(lastAt);
+
+      const title = `${source} · ${ownerName} ↔ ${otherNames} · ${firstYmd}→${lastYmd}`;
+
+      // 4. Stamp the title. Guarded by `title IS NULL` so a concurrent live
+      //    ingest that has already written a real title is never overwritten.
+      const upd = await session.run(
+        `MATCH (a:ConversationArchive)
+         WHERE elementId(a) = $elemId AND a.title IS NULL
+         SET a.title = $title
+         RETURN count(a) AS n`,
+        { elemId, title },
+      );
+      const n = upd.records[0]?.get("n");
+      const v = typeof n === "number" ? n : (n as { toNumber?: () => number })?.toNumber?.() ?? 0;
+      if (v > 0) archivesTitled += 1;
+    }
+
+    console.error(
+      `[migration:conversation-archive-title] ` +
+        `archives-titled=${archivesTitled} ` +
+        `degraded-no-dates=${degradedNoDates} ` +
+        `degraded-no-names=${degradedNoNames}`,
+    );
+  } finally {
+    await session.close();
+  }
+}

package/payload/platform/neo4j/schema.cypher

@@ -850,7 +850,7 @@ FOR (a:Agent) ON (a.accountId);
 // (not account-scoped). Linked to accounts via ADMIN_OF.
 //
 // Properties:
-//   userId     — UUID, matches entry in platform/config/users.json
+//   userId     — UUID, matches entry in ~/<brand.configDir>/users.json (Task 904; pre-Task-904 path was platform/config/users.json)
 //   name       — display name (e.g. "Adam")
 //   createdAt  — ISO 8601 timestamp
 //

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

package/payload/platform/plugins/admin/PLUGIN.md

@@ -44,7 +44,7 @@ Platform management tools for both the admin and public agents. The `plugin-read
 
 Tools are available via the `admin` MCP server.
 
-**Three-store admin auth invariant.** `admin-add` writes to all three identity stores (`users.json` PIN auth, `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same line. Direct `Edit`/`Write` on `account.json` is blocked at the `pre-tool-use` hook — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
+**Three-store admin auth invariant.** `admin-add` writes to all three identity stores (`users.json` PIN auth at the persistent `~/{configDir}/users.json` location , `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines plus the `[admins-write]` chokepoint line, and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same `[admin-auth-store]` line. **Single chokepoint:** every `users.json` + `account.json admins[]` mutation routes through `platform/lib/admins-write` (`writeAdminEntry` for admin-add/set-pin, `removeAdminFromAccount` for admin-remove); the static check `grep -rnE 'admins\.push\|config\.admins\s*=' platform/ \| grep -v lib/admins-write` returns 0. Direct `Edit`/`Write` on `account.json` is blocked at the `pre-tool-use` hook — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. **Install + boot invariants:** the installer and admin-server boot walk every account.json admins[] vs users.json; `[install-invariant]` / `[admin-invariant] direction=… userId=<id8> source=<file>` fires per divergence with a `check complete divergences=<n>` summary. Log-only — does not block. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
 
 `logs-read { type: "agent-stream" }` is the canonical name for the per-conversation tool-use/tool-result archive previously called `system`; both names work and the legacy alias is preserved.