@rubytech/create-maxy-code 0.1.533 → 0.1.535

package/payload/server/server.js

@@ -67,6 +67,7 @@ import {
   MAX_DATA_UPLOAD_BYTES,
   MAX_FILES_PER_MESSAGE,
   MAX_FILE_SIZE_BYTES,
+  PARTY_LABEL_PATTERN,
   STORE_ROOT,
   SUPPORTED_MIME_TYPES,
   WHATSAPP_DOCUMENT_MAX_BYTES,
@@ -156,6 +157,7 @@ import {
   recordAccessFailedAttempt,
   recordRequestLinkAttempt,
   registerLoginSocket,
+  registeredPartyFor,
   reloadConfig,
   resolveAccountConfig,
   resolveClaudeUploadsPath,
@@ -190,7 +192,7 @@ import {
   waitForConnection,
   warnNonUuidAccount,
   writeChatMetadataMerged
-} from "./chunk-AJC3SQSF.js";
+} from "./chunk-4QCYFTAI.js";
 import {
   ACCOUNTS_DIR,
   BIN_DIR,
@@ -5019,7 +5021,7 @@ async function defaultHttpGet(url) {
   }
 }
 async function defaultResolve(accountId) {
-  const { resolveSocket: resolveSocket2 } = await import("./manager-PLRHVALC.js");
+  const { resolveSocket: resolveSocket2 } = await import("./manager-ZNHQQCED.js");
   return resolveSocket2(accountId);
 }
 async function fetchAvatar(accountId, jid, deps = {}) {
@@ -5404,6 +5406,10 @@ function addAdminPhone(accountDir, phone) {
         error: `${targetId} does not own the WhatsApp paired socket, so its admin phones are never consulted. To route a phone to a sub-account, bind it as an account manager (add-account-manager) instead.`
       };
     }
+    if (registeredPartyFor(readRegisteredPartiesFrom(config), normalized)) {
+      console.error(`${TAG10} add-admin-phone rejected phone=${normalized} reason=party-registration-shadowed`);
+      return { ok: false, reason: "party-registration-shadowed", error: partyShadowMessage(normalized, "registeredParties") };
+    }
     if (!config.whatsapp || typeof config.whatsapp !== "object") {
       config.whatsapp = {};
     }
@@ -5605,6 +5611,10 @@ function setAccountManager(accountDir, phone, subAccountId, mode = "active") {
         error: `The account-manager routing table is read from ${houseId}'s account.json only, so a binding stored on ${targetId} is never consulted. Bind ${normalized} on ${houseId} instead.`
       };
     }
+    if (registeredPartyFor(readRegisteredPartiesFrom(config), normalized)) {
+      console.error(`${TAG10} set-account-manager rejected phone=${normalized} reason=party-registration-shadowed`);
+      return { ok: false, reason: "party-registration-shadowed", error: partyShadowMessage(normalized, "registeredParties") };
+    }
     if (!config.whatsapp || typeof config.whatsapp !== "object") {
       config.whatsapp = {};
     }
@@ -5633,6 +5643,200 @@ function setAccountManager(accountDir, phone, subAccountId, mode = "active") {
     return { ok: false, error: msg };
   }
 }
+function readRegisteredPartiesFrom(config) {
+  const wa = config.whatsapp;
+  const map = wa?.registeredParties;
+  if (!map || typeof map !== "object" || Array.isArray(map)) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(map)) {
+    if (v && typeof v === "object" && typeof v.account === "string" && typeof v.party === "string") {
+      out[k] = { account: v.account, party: v.party };
+    }
+  }
+  return out;
+}
+function partyShadowedBy(wa, phone) {
+  const adminPhones = Array.isArray(wa.adminPhones) ? wa.adminPhones.filter((p) => typeof p === "string") : [];
+  if (isAdminPhone(phone, adminPhones)) return "adminPhones";
+  const managers = wa.accountManagers && typeof wa.accountManagers === "object" && !Array.isArray(wa.accountManagers) ? wa.accountManagers : {};
+  if (managedAccountFor(managers, phone)) return "accountManagers";
+  return null;
+}
+function partyShadowMessage(phone, shadowedBy) {
+  if (shadowedBy === "registeredParties") {
+    return `${phone} is already a registered party. Arms 1-4 of the inbound gate all precede the registered-party arm, so adding this registration would silently disable the party binding rather than layering on it. Remove the party registration first (remove-registered-party) if that is what you intend.`;
+  }
+  const surface = shadowedBy === "adminPhones" ? "an admin phone" : "an account manager";
+  const remedy = shadowedBy === "adminPhones" ? "remove-admin-phone" : "remove-account-manager";
+  return `${phone} is already ${surface}. Arms 1-4 of the inbound gate all precede the registered-party arm, so this registration would never be reached. Remove the existing registration first (${remedy}) if you want this phone treated as a counterparty rather than an operator.`;
+}
+function setRegisteredParty(accountDir, phone, account, party) {
+  const normalized = phone.trim();
+  if (!E164_PATTERN.test(normalized)) {
+    return { ok: false, error: `Invalid phone format "${normalized}". Expected E.164 (e.g. +441234567890).` };
+  }
+  const label = party.trim();
+  if (!PARTY_LABEL_PATTERN.test(label)) {
+    return {
+      ok: false,
+      reason: "invalid-party-label",
+      error: `Invalid party label "${label}". Use 1-64 characters of lowercase letters, digits and hyphens (e.g. "driver").`
+    };
+  }
+  const acct = account.trim();
+  if (!acct) return { ok: false, error: "Missing account id." };
+  let validIds;
+  try {
+    validIds = listValidAccounts().map((a) => a.accountId);
+  } catch (err) {
+    return { ok: false, error: `Could not read the account registry to validate the account: ${err instanceof Error ? err.message : String(err)}. Try again.` };
+  }
+  if (!validIds.includes(acct)) {
+    return { ok: false, error: `Account "${acct}" is not in this install's account registry. Check the id and try again.` };
+  }
+  let houseId;
+  try {
+    houseId = resolveHouseOrSoleAccountId(dirname2(resolve5(accountDir)));
+  } catch (err) {
+    return { ok: false, error: `Could not resolve the house account to validate the registration: ${err instanceof Error ? err.message : String(err)}. Try again.` };
+  }
+  if (acct === houseId) {
+    console.error(`${TAG10} set-registered-party rejected phone=${normalized} reason=house-account-binding`);
+    return {
+      ok: false,
+      reason: "house-account-binding",
+      error: `${acct} is the house account. A registered party is admitted only on the account's OWN number, and on the house number they take the house DM policy instead, so a house registration would never be consulted.`
+    };
+  }
+  try {
+    const config = readConfig(accountDir);
+    const targetId = typeof config.accountId === "string" && config.accountId ? config.accountId : basename(resolve5(accountDir));
+    if (targetId !== houseId) {
+      console.error(`${TAG10} set-registered-party rejected phone=${normalized} reason=not-socket-account`);
+      return {
+        ok: false,
+        reason: "not-socket-account",
+        error: `The registered-party table is read from ${houseId}'s account.json only, so a registration stored on ${targetId} is never consulted. Register ${normalized} on ${houseId} instead.`
+      };
+    }
+    if (!config.whatsapp || typeof config.whatsapp !== "object") {
+      config.whatsapp = {};
+    }
+    const wa = config.whatsapp;
+    const shadow = partyShadowedBy(wa, normalized);
+    if (shadow) {
+      console.error(`${TAG10} set-registered-party rejected phone=${normalized} reason=party-registration-shadowed shadowedBy=${shadow}`);
+      return { ok: false, reason: "party-registration-shadowed", error: partyShadowMessage(normalized, shadow) };
+    }
+    if (!wa.registeredParties || typeof wa.registeredParties !== "object") {
+      wa.registeredParties = {};
+    }
+    wa.registeredParties[normalized] = { account: acct, party: label };
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config.whatsapp = parsed.data;
+    writeConfig(accountDir, config);
+    console.error(`${TAG10} registered party phone=${normalized} account=${acct} party=${label}`);
+    reloadManagerConfig(accountDir);
+    return {
+      ok: true,
+      message: `Registered ${normalized} as "${label}" for account ${acct}. Their WhatsApp messages to that account's own number reach its public agent carrying the label; they are not granted admin, and on the house number they take the house DM policy.`
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG10} setRegisteredParty failed: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function clearRegisteredParty(accountDir, phone) {
+  const normalized = phone.trim();
+  try {
+    const config = readConfig(accountDir);
+    const wa = config.whatsapp;
+    if (!wa || typeof wa !== "object" || !wa.registeredParties || typeof wa.registeredParties !== "object") {
+      return { ok: true, message: `No registered-party registration for ${normalized}.` };
+    }
+    const map = wa.registeredParties;
+    const key = Object.keys(map).find((k) => phonesMatch(k, normalized));
+    if (!key) {
+      return { ok: true, message: `No registered-party registration for ${normalized}.` };
+    }
+    delete map[key];
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config.whatsapp = parsed.data;
+    writeConfig(accountDir, config);
+    console.error(`${TAG10} cleared registered party phone=${normalized}`);
+    reloadManagerConfig(accountDir);
+    return { ok: true, message: `Cleared the registered-party registration for ${normalized}.` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG10} clearRegisteredParty failed: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function readRegisteredParties(accountDir) {
+  try {
+    return readRegisteredPartiesFrom(readConfig(accountDir));
+  } catch {
+    return {};
+  }
+}
+function purgeNonSocketRegisteredParties(accountDir, socketOwnerId) {
+  try {
+    const config = readConfig(accountDir);
+    const wa = config.whatsapp;
+    if (!wa || typeof wa !== "object") return { removed: [] };
+    const targetId = typeof config.accountId === "string" && config.accountId ? config.accountId : basename(resolve5(accountDir));
+    if (targetId === socketOwnerId) return { removed: [] };
+    const map = wa.registeredParties;
+    if (!map || typeof map !== "object" || Array.isArray(map)) return { removed: [] };
+    const removed = Object.entries(map).map(([phone, entry]) => ({
+      phone,
+      account: entry && typeof entry === "object" && typeof entry.account === "string" ? entry.account : "",
+      party: entry && typeof entry === "object" && typeof entry.party === "string" ? entry.party : ""
+    }));
+    if (removed.length === 0) return { removed: [] };
+    delete wa.registeredParties;
+    writeConfig(accountDir, config);
+    for (const { phone, account, party } of removed) {
+      console.error(`[admin-identity] op=purge-nonsocket-registeredparty accountId=${targetId} phone=${phone} account=${account} party=${party} removed=true`);
+    }
+    return { removed };
+  } catch (err) {
+    console.error(`[admin-identity] purge-nonsocket-registeredparty failed dir=${accountDir}: ${String(err)}`);
+    return { removed: [] };
+  }
+}
+function purgeNonSocketRegisteredPartiesAtBoot() {
+  let socketOwner;
+  try {
+    socketOwner = resolveHouseOrSoleAccountId(ACCOUNTS_DIR);
+  } catch (err) {
+    console.error(`[admin-identity] purge-nonsocket-registeredparty skipped \u2014 cannot resolve socket owner: ${String(err)}`);
+    return;
+  }
+  const configOwner = resolveAccount()?.accountId ?? null;
+  if (configOwner !== socketOwner) {
+    console.error(`[admin-identity] purge-nonsocket-registeredparty skipped \u2014 resolver disagreement house=${socketOwner} configLoadedFrom=${configOwner ?? "unresolved"}`);
+    return;
+  }
+  let accounts;
+  try {
+    accounts = listValidAccounts();
+  } catch {
+    return;
+  }
+  for (const acct of accounts) {
+    purgeNonSocketRegisteredParties(acct.accountDir, socketOwner);
+  }
+}
 function setDispatchInbound(accountDir, accountId, value, ctx) {
   const id = accountId.trim();
   if (!id) return { ok: false, reason: "missing-account-id", error: "Missing account id." };
@@ -6299,6 +6503,60 @@ function reconcileConnectionAccountStamps(input) {
   return { ok: mismatches.length === 0, mismatches };
 }
 
+// app/lib/whatsapp/person-identity-reconcile.ts
+function bare(value) {
+  return value.startsWith("+") ? value.slice(1) : value;
+}
+function reconcilePersonIdentities(rows) {
+  const perAccount = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    let entry = perAccount.get(row.accountId);
+    if (!entry) {
+      entry = { seen: /* @__PURE__ */ new Map(), divergent: 0 };
+      perAccount.set(row.accountId, entry);
+    }
+    const p = row.phone ? bare(row.phone) : null;
+    const t = row.telephone ? bare(row.telephone) : null;
+    if (p && t && p !== t) entry.divergent += 1;
+    const key = p ?? t;
+    if (key) entry.seen.set(key, (entry.seen.get(key) ?? 0) + 1);
+  }
+  const accounts = [];
+  let duplicates = 0;
+  let divergent = 0;
+  for (const [accountId, entry] of perAccount) {
+    let dup = 0;
+    for (const count of entry.seen.values()) if (count > 1) dup += count - 1;
+    duplicates += dup;
+    divergent += entry.divergent;
+    if (dup > 0 || entry.divergent > 0) {
+      accounts.push({ accountId, duplicates: dup, divergent: entry.divergent });
+    }
+  }
+  return {
+    ok: duplicates === 0 && divergent === 0,
+    checked: rows.length,
+    duplicates,
+    divergent,
+    accounts
+  };
+}
+
+// app/lib/whatsapp/notify-manager-recipients.ts
+function recipientsForAccount(managers, accountId) {
+  const out = [];
+  for (const [phone, value] of Object.entries(managers ?? {})) {
+    let bound = null;
+    if (typeof value === "string") {
+      bound = value;
+    } else if (value && typeof value === "object" && typeof value.managesAccount === "string") {
+      bound = value.managesAccount;
+    }
+    if (bound !== null && bound === accountId) out.push(phone);
+  }
+  return out;
+}
+
 // app/lib/whatsapp/self-phone-admin-reconcile.ts
 var HOUSE_CREDENTIAL_DIRNAME = "default";
 function reconcileSelfPhoneAdmins(input) {
@@ -6712,6 +6970,22 @@ function authorizeRecallRead(input) {
   };
 }
 
+// app/lib/whatsapp/registered-party-reconcile.ts
+function buildRegisteredPartyReconcile(params) {
+  const rows = [];
+  const entries2 = Object.entries(params.registeredParties);
+  for (const [phone, entry] of entries2) {
+    const shadowedBy = isAdminPhone(phone, params.adminPhones) ? "adminPhones" : managedAccountFor(params.accountManagers, phone) ? "accountManagers" : null;
+    const unresolved2 = !params.isValidAccount(entry.account);
+    if (shadowedBy || unresolved2) {
+      rows.push({ phone, account: entry.account, party: entry.party, shadowedBy, unresolved: unresolved2 });
+    }
+  }
+  const shadowed = rows.filter((r) => r.shadowedBy !== null).length;
+  const unresolved = rows.filter((r) => r.unresolved).length;
+  return { ok: shadowed === 0 && unresolved === 0, checked: entries2.length, shadowed, unresolved, rows };
+}
+
 // server/routes/whatsapp.ts
 var TAG15 = "[whatsapp:api]";
 var PLATFORM_ROOT3 = process.env.MAXY_PLATFORM_ROOT || "";
@@ -6748,10 +7022,11 @@ function evaluateCallerScope(c, requestedAccountId) {
   const decision = authorizeRecallRead({ requestedAccountId, callerAccountId, houseAdminScope });
   return { decision, callerAccountId, houseAdminScope };
 }
-function callerScopeDenial(c, requestedAccountId) {
+function callerScopeDenial(c, requestedAccountId, targetSource) {
   const { decision, callerAccountId, houseAdminScope } = evaluateCallerScope(c, requestedAccountId);
   if (decision.authorized) return { denial: null, callerAccountId };
-  console.error(`[whatsapp-read-tool] op=authz-deny requested=${requestedAccountId} caller=${callerAccountId ?? "none"} houseAdmin=${houseAdminScope ? "y" : "n"}`);
+  const source = targetSource ? ` targetSource=${targetSource}` : "";
+  console.error(`[whatsapp-read-tool] op=authz-deny requested=${requestedAccountId}${source} caller=${callerAccountId ?? "none"} houseAdmin=${houseAdminScope ? "y" : "n"}`);
   return { denial: c.json({ error: decision.reason }, 403), callerAccountId };
 }
 function houseSocketScopeDenial(c, op) {
@@ -6860,6 +7135,44 @@ app3.get("/status", async (c) => {
     if (!outboundSocketReconcile.ok) {
       console.warn(`${TAG15} outbound-caller-unsigned-drift unsigned=${outboundSocketReconcile.unsignedFallbacks} of=${outboundSocketReconcile.checked} \u2014 at least one agent send carried no caller identity and left on the house socket; if it came from a sub-account session the recipient saw the wrong sender number`);
     }
+    const registeredPartyReconcile = buildRegisteredPartyReconcile({
+      registeredParties: accountDir ? readRegisteredParties(accountDir) : {},
+      adminPhones: accountDir ? readAdminPhones(accountDir) : [],
+      accountManagers: accountDir ? readAccountManagers(accountDir) : {},
+      isValidAccount: (id) => isProvisionedAccount(join15(MAXY_DIR, "data", "accounts"), id)
+    });
+    console.error(`${TAG15} op=registered-party-reconcile checked=${registeredPartyReconcile.checked} shadowed=${registeredPartyReconcile.shadowed} unresolved=${registeredPartyReconcile.unresolved} ok=${registeredPartyReconcile.ok}`);
+    for (const row of registeredPartyReconcile.rows) {
+      if (row.shadowedBy) {
+        console.warn(`${TAG15} registered-party-shadowed phone=${row.phone} shadowedBy=${row.shadowedBy} \u2014 this counterparty is registered on this account but an earlier gate arm wins, so they reach the agent as an operator, not a party; remove the ${row.shadowedBy === "adminPhones" ? "admin phone" : "account-manager binding"} or the party registration`);
+      }
+      if (row.unresolved) {
+        console.warn(`${TAG15} registered-party-unresolved phone=${row.phone} account=${row.account} \u2014 this registration names an account that is not in the registry, so every message from them on that number is hard-rejected`);
+      }
+    }
+    let personIdentityReconcile = { ok: true, checked: 0, duplicates: 0, divergent: 0, accounts: [] };
+    try {
+      const identitySession = getSession();
+      try {
+        const identityRes = await identitySession.run(
+          `MATCH (p:Person) WHERE p.accountId IS NOT NULL
+           RETURN p.accountId AS accountId, p.phone AS phone, p.telephone AS telephone`
+        );
+        const identityRows = identityRes.records.map((r) => ({
+          accountId: String(r.get("accountId")),
+          phone: r.get("phone") ?? null,
+          telephone: r.get("telephone") ?? null
+        }));
+        personIdentityReconcile = reconcilePersonIdentities(identityRows);
+      } finally {
+        await identitySession.close();
+      }
+    } catch (err) {
+      personIdentityReconcile = { ok: false, checked: 0, duplicates: 0, divergent: 0, accounts: [], reason: String(err) };
+    }
+    if (!personIdentityReconcile.ok) {
+      console.warn(`${TAG15} person-identity-drift duplicates=${personIdentityReconcile.duplicates} divergent=${personIdentityReconcile.divergent} of=${personIdentityReconcile.checked} \u2014 a WhatsApp sender may resolve to the wrong :Person or to none`);
+    }
     let routineScopeReconcile = null;
     let neo = null;
     try {
@@ -6916,7 +7229,7 @@ app3.get("/status", async (c) => {
     const inheritanceSummary = policyInheritance.rows.map((r) => `${r.accountId}:${r.dmPolicy}/${r.adminPhones}/${r.allowFrom}`).join(", ");
     console.error(`${TAG15} op=policy-inheritance rows=${policyInheritance.rows.length} inheriting=${policyInheritance.inheritedCount} [${inheritanceSummary}]`);
     console.error(`${TAG15} op=status-projection caller=${callerAccountId?.slice(0, 8) ?? "none"} scope=house rows=${accounts.length}`);
-    return c.json({ accounts, storeKeyReconcile, connectionAccountReconcile, selfPhoneAdminReconcile, outboundSocketReconcile, routineScopeReconcile, bindingAccountDrift, policyInheritance });
+    return c.json({ accounts, storeKeyReconcile, connectionAccountReconcile, selfPhoneAdminReconcile, outboundSocketReconcile, registeredPartyReconcile, routineScopeReconcile, bindingAccountDrift, policyInheritance, personIdentityReconcile });
   } catch (err) {
     console.error(`${TAG15} status error: ${String(err)}`);
     return c.json({ error: String(err) }, 500);
@@ -6999,7 +7312,7 @@ app3.post("/reconnect", async (c) => {
 app3.post("/config", async (c) => {
   try {
     const body = await c.req.json().catch(() => ({}));
-    const { action, phone, slug, fields, accountId, managesAccount, mode, policy } = body;
+    const { action, phone, slug, fields, accountId, managesAccount, mode, policy, party, account: partyAccount } = body;
     if (!action || typeof action !== "string") {
       return c.json({ ok: false, error: 'Missing required field "action".' }, 400);
     }
@@ -7083,6 +7396,46 @@ app3.post("/config", async (c) => {
       console.error(`${TAG15} config action=remove-account-manager phone=${phone} boundTo=${bound?.account ?? "none"} caller=${callerAccountId || "none"} ok=${result.ok}`);
       return c.json(result, result.ok ? 200 : 400);
     }
+    if (action === "add-registered-party" || action === "remove-registered-party" || action === "list-registered-parties") {
+      const acct = resolveAccount();
+      if (!acct) return c.json({ ok: false, error: "No account configured." }, 500);
+      const callerAccountId = c.req.header("x-maxy-caller-account")?.trim() || "";
+      const houseAdminScope = c.req.header("x-maxy-house-admin-scope")?.trim() || null;
+      const houseAdmin = !!houseAdminScope || !!callerAccountId && callerAccountId === acct.accountId;
+      if (action === "list-registered-parties") {
+        const listDenial = bindingScopeDenial(c, callerAccountId, "list-registered-parties");
+        if (listDenial) return listDenial;
+        const all = readRegisteredParties(acct.accountDir);
+        const registeredParties = houseAdmin ? all : Object.fromEntries(Object.entries(all).filter(([, entry]) => entry.account === callerAccountId));
+        console.error(`${TAG15} config action=list-registered-parties caller=${callerAccountId || "none"} houseAdmin=${houseAdmin ? "y" : "n"} count=${Object.keys(registeredParties).length} of=${Object.keys(all).length}`);
+        return c.json({ ok: true, registeredParties });
+      }
+      if (!phone || typeof phone !== "string") {
+        return c.json({ ok: false, error: 'Missing required field "phone" (E.164 format, e.g. +441234567890).' }, 400);
+      }
+      if (action === "add-registered-party") {
+        if (!partyAccount || typeof partyAccount !== "string") {
+          return c.json({ ok: false, error: 'Missing required field "account" (the account whose own number this phone is a counterparty on).' }, 400);
+        }
+        if (!party || typeof party !== "string") {
+          return c.json({ ok: false, error: 'Missing required field "party" (the label for this counterparty, e.g. "driver").' }, 400);
+        }
+        const addDenial = bindingScopeDenial(c, partyAccount, "add-registered-party");
+        if (addDenial) return addDenial;
+        const result2 = setRegisteredParty(acct.accountDir, phone, partyAccount, party);
+        const partyReasonTail = !result2.ok && result2.reason ? ` reason=${result2.reason}` : "";
+        console.error(`${TAG15} config action=add-registered-party phone=${phone} account=${partyAccount} caller=${callerAccountId || "none"} ok=${result2.ok}${partyReasonTail}`);
+        return c.json(result2, result2.ok ? 200 : 400);
+      }
+      const registered = registeredPartyFor(readRegisteredParties(acct.accountDir), phone);
+      if (!houseAdmin) {
+        const removePartyDenial = bindingScopeDenial(c, registered?.account ?? "", "remove-registered-party");
+        if (removePartyDenial) return removePartyDenial;
+      }
+      const result = clearRegisteredParty(acct.accountDir, phone);
+      console.error(`${TAG15} config action=remove-registered-party phone=${phone} registeredTo=${registered?.account ?? "none"} caller=${callerAccountId || "none"} ok=${result.ok}`);
+      return c.json(result, result.ok ? 200 : 400);
+    }
     const denial = houseSocketScopeDenial(c, `config action=${action}`);
     if (denial) return denial;
     const account = resolveAccount();
@@ -7245,14 +7598,15 @@ app3.post("/send-admin", async (c) => {
     const adminPhones = readAdminPhones(account.accountDir);
     const isAdmin = isAdminPhone(phone, adminPhones);
     const managerMatch = isAdmin ? null : managedAccountFor(readAccountManagers(account.accountDir), phone);
-    if (!isAdmin && !managerMatch) {
+    const partyMatch = isAdmin || managerMatch ? null : registeredPartyFor(readRegisteredParties(account.accountDir), phone);
+    if (!isAdmin && !managerMatch && !partyMatch) {
       console.error(`[whatsapp:outbound] op=send-refused reason=not-admin-phone to=${phone} account=${sendAccountId}`);
       return c.json(
-        { error: `Refused: ${phone} is not a registered admin phone or account manager for this install. Only a number registered with whatsapp-config (add-admin-phone or add-account-manager) can receive an agent-initiated send.` },
+        { error: `Refused: ${phone} is not a registered admin phone, account manager or registered party for this install. Only a number registered with whatsapp-config (add-admin-phone, add-account-manager or add-registered-party) can receive an agent-initiated send.` },
         403
       );
     }
-    const via = isAdmin ? "admin-phone" : "account-manager";
+    const via = isAdmin ? "admin-phone" : managerMatch ? "account-manager" : "registered-party";
     const res = resolveSocket(sendAccountId);
     if (!res.ok) {
       if (res.reason === "key-miss") {
@@ -7273,6 +7627,59 @@ app3.post("/send-admin", async (c) => {
     return c.json({ error: String(err) }, 500);
   }
 });
+app3.post("/notify-manager", async (c) => {
+  try {
+    const body = await c.req.json().catch(() => ({}));
+    const { senderDisplay, summary, draftLocation } = body;
+    for (const [field2, value] of [["senderDisplay", senderDisplay], ["summary", summary], ["draftLocation", draftLocation]]) {
+      if (typeof value !== "string" || value.trim().length === 0) {
+        return c.json({ error: `Missing required field "${field2}".` }, 400);
+      }
+    }
+    const account = resolveAccount();
+    if (!account) return c.json({ error: "No account configured." }, 500);
+    const callerAccountId = c.req.header("x-maxy-caller-account")?.trim() || null;
+    if (!callerAccountId) {
+      console.error(`[whatsapp:outbound] op=notify-manager-refused reason=caller-unsigned`);
+      return c.json({ error: "Refused: this request carried no caller identity, so there is no account whose managers to notify.", reason: "caller-unsigned" }, 403);
+    }
+    const notifyAccountId = callerAccountId;
+    const recipients = recipientsForAccount(readAccountManagers(account.accountDir), notifyAccountId);
+    if (recipients.length === 0) {
+      console.error(`[whatsapp:outbound] op=notify-manager-refused reason=no-registered-manager account=${notifyAccountId}`);
+      return c.json({ error: `Refused: no account manager is registered for account "${notifyAccountId}". Register one with whatsapp-config add-account-manager.`, reason: "no-registered-manager" }, 403);
+    }
+    const res = resolveSocket(notifyAccountId);
+    if (!res.ok) {
+      if (res.reason === "key-miss") {
+        console.error(`[whatsapp:outbound] op=socket-key-miss accountId=${notifyAccountId} presentKeys=${res.presentKeys.join(",") || "none"}`);
+        return c.json({ error: `No WhatsApp socket is registered for account "${notifyAccountId}" (present: ${res.presentKeys.join(", ") || "none"}). This is an account-keying mismatch, not a dropped connection.` }, 503);
+      }
+      return c.json({ error: `WhatsApp account "${notifyAccountId}" is registered but its socket is disconnected.` }, 503);
+    }
+    const text = `New WhatsApp message from ${senderDisplay}.
+
+${summary}
+
+A reply has been drafted: ${draftLocation}`;
+    const delivered = [];
+    const failed = [];
+    for (const phone of recipients) {
+      const sent = await sendTextMessage(res.sock, normalizeE164(phone), text, { accountId: res.accountId });
+      if (sent.success) delivered.push(phone);
+      else failed.push(phone);
+    }
+    recordOutboundSend(callerAccountId, notifyAccountId);
+    console.error(`[whatsapp:outbound] op=notify-manager-ok account=${notifyAccountId} socketAccount=${res.accountId} delivered=${delivered.length} failed=${failed.length}`);
+    if (delivered.length === 0) {
+      return c.json({ error: "Notification failed for every registered manager.", failed }, 502);
+    }
+    return c.json({ success: true, delivered, failed });
+  } catch (err) {
+    console.error(`${TAG15} notify-manager error: ${String(err)}`);
+    return c.json({ error: String(err) }, 500);
+  }
+});
 app3.post("/reply", async (c) => {
   const sendId = process.hrtime.bigint().toString(36).slice(-8);
   try {
@@ -7349,8 +7756,8 @@ app3.get("/activity", (c) => {
 });
 app3.get("/conversations", (c) => {
   try {
-    const requestedAccountId = validateAccountId(c.req.query("accountId") ?? null);
-    const { denial, callerAccountId } = callerScopeDenial(c, requestedAccountId);
+    const { accountId: requestedAccountId, targetSource } = resolveLifecycleAccountId(c, c.req.query("accountId") ?? null);
+    const { denial, callerAccountId } = callerScopeDenial(c, requestedAccountId, targetSource);
     if (denial) return denial;
     const projection = projectionFor(requestedAccountId);
     const storeAccountId = resolveReadStoreKey(projection.storeAccountId);
@@ -7371,7 +7778,7 @@ app3.get("/conversations", (c) => {
       };
     });
     conversations.sort((a, b) => (b.lastMessageTimestamp ?? 0) - (a.lastMessageTimestamp ?? 0));
-    console.error(`${TAG15} conversations requested=${requestedAccountId} caller=${callerAccountId ?? "none"} account=${storeAccountId} projected=${projecting} storeAccount=${projecting ? storeAccountId : "self"} managerPhonesBound=${managerPhonesBound} storeKeyFound=${allConversations.size > 0} count=${conversations.length}`);
+    console.error(`${TAG15} conversations requested=${requestedAccountId} targetSource=${targetSource} caller=${callerAccountId ?? "none"} account=${storeAccountId} projected=${projecting} storeAccount=${projecting ? storeAccountId : "self"} managerPhonesBound=${managerPhonesBound} storeKeyFound=${allConversations.size > 0} count=${conversations.length}`);
     return c.json({ conversations });
   } catch (err) {
     console.error(`${TAG15} conversations error: ${String(err)}`);
@@ -7380,8 +7787,8 @@ app3.get("/conversations", (c) => {
 });
 app3.get("/messages", (c) => {
   try {
-    const requestedAccountId = validateAccountId(c.req.query("accountId") ?? null);
-    const { denial, callerAccountId } = callerScopeDenial(c, requestedAccountId);
+    const { accountId: requestedAccountId, targetSource } = resolveLifecycleAccountId(c, c.req.query("accountId") ?? null);
+    const { denial, callerAccountId } = callerScopeDenial(c, requestedAccountId, targetSource);
     if (denial) return denial;
     const jid = c.req.query("jid");
     if (!jid) {
@@ -7427,7 +7834,7 @@ app3.get("/messages", (c) => {
         ...reactions && reactions.length > 0 ? { reactions } : {}
       };
     });
-    console.error(`${TAG15} messages requested=${requestedAccountId} caller=${callerAccountId ?? "none"} account=${storeAccountId} jid=${jid} projected=${projecting} storeAccount=${projecting ? storeAccountId : "self"} managerPhonesBound=${managerPhonesBound} storeKeyFound=${storeMessages.length > 0} limit=${effectiveLimit ?? "all"} returned=${messages.length} withAttachments=${withAttachments}`);
+    console.error(`${TAG15} messages requested=${requestedAccountId} targetSource=${targetSource} caller=${callerAccountId ?? "none"} account=${storeAccountId} jid=${jid} projected=${projecting} storeAccount=${projecting ? storeAccountId : "self"} managerPhonesBound=${managerPhonesBound} storeKeyFound=${storeMessages.length > 0} limit=${effectiveLimit ?? "all"} returned=${messages.length} withAttachments=${withAttachments}`);
     return c.json({ messages });
   } catch (err) {
     console.error(`${TAG15} messages error: ${String(err)}`);
@@ -7537,19 +7944,21 @@ app3.get("/conversation-graph-state", async (c) => {
   }
 });
 app3.get("/group-info", async (c) => {
-  const accountId = validateAccountId(c.req.query("accountId") ?? null);
+  const { accountId, targetSource } = resolveLifecycleAccountId(c, c.req.query("accountId") ?? null);
+  const callerAccountId = c.req.header("x-maxy-caller-account")?.trim() || null;
+  const scope = `account=${accountId} targetSource=${targetSource} caller=${callerAccountId ?? "none"}`;
   const jid = c.req.query("jid");
   try {
     if (!jid) {
       return c.json({ error: "Missing required parameter: jid" }, 400);
     }
     if (!isGroupJid(jid)) {
-      console.error(`${TAG15} group-info error="not a group JID" jid=${jid} account=${accountId}`);
+      console.error(`${TAG15} group-info error="not a group JID" jid=${jid} ${scope}`);
       return c.json({ error: `"${jid}" is not a group JID. Group JIDs end with @g.us.` }, 400);
     }
     const res = resolveSocket(accountId);
     if (!res.ok) {
-      console.error(`${TAG15} group-info error="${formatSocketResolutionReason(res)}" account=${accountId}`);
+      console.error(`${TAG15} group-info error="${formatSocketResolutionReason(res)}" ${scope}`);
       return c.json({ error: formatSocketResolutionMessage(res, accountId) }, 400);
     }
     const sock = res.sock;
@@ -7563,10 +7972,10 @@ app3.get("/group-info", async (c) => {
       participantCount: meta.participants.length,
       participants: meta.participants.map((p) => ({ jid: p.id, admin: p.admin ?? null }))
     };
-    console.error(`${TAG15} group-info jid=${jid} subject="${meta.subject}" participants=${meta.participants.length} account=${accountId}`);
+    console.error(`${TAG15} group-info jid=${jid} subject="${meta.subject}" participants=${meta.participants.length} ${scope}`);
     return c.json(result);
   } catch (err) {
-    console.error(`${TAG15} group-info error="${String(err)}" jid=${jid} account=${accountId}`);
+    console.error(`${TAG15} group-info error="${String(err)}" jid=${jid} ${scope}`);
     return c.json({ error: `Failed to fetch group info: ${String(err)}` }, 500);
   }
 });
@@ -9437,8 +9846,8 @@ var MAX_FILE_BYTES = 50 * 1024 * 1024;
 
 // app/lib/audio-attachment-mime.ts
 function isMimeAdmitted(mimeType, supportedSet) {
-  const bare = mimeType.split(";")[0].trim().toLowerCase();
-  return supportedSet.has(bare);
+  const bare2 = mimeType.split(";")[0].trim().toLowerCase();
+  return supportedSet.has(bare2);
 }
 
 // server/lib/stream-offset.ts
@@ -16305,7 +16714,19 @@ var ALLOWED_EVENTS = /* @__PURE__ */ new Set([
   "device-url:malformed",
   // Task 2074 — the client receipt proving a notification card actually
   // painted. The only signal that distinguishes "delivered" from "rendered".
-  "wa-notify:rendered"
+  "wa-notify:rendered",
+  // Task 2138 — the desktop-notification surface.
+  //
+  // `desktop-capability` is posted once per AdminShell mount and is the only
+  // signal that does not need a message to arrive: on a plain-HTTP LAN origin
+  // the Notification API is unavailable and `requestPermission()` returns
+  // "denied" with no prompt, so without this line that install reports nothing
+  // and reads as "no messages yet".
+  //
+  // `desktop-outcome` carries one verdict per message — `shown`, a skip reason,
+  // or `construct-failed` — so a missing banner is always explained.
+  "wa-notify:desktop-capability",
+  "wa-notify:desktop-outcome"
 ]);
 var app24 = new Hono();
 app24.post("/", async (c) => {
@@ -21797,7 +22218,8 @@ async function managerRcSpawn(opts) {
       role: opts.role,
       channel: opts.channel,
       senderId: opts.senderId,
-      targetAccountId: opts.targetAccountId
+      targetAccountId: opts.targetAccountId,
+      party: opts.party
     })
   }).catch((err) => ({ __throw: err instanceof Error ? err.message : String(err) }));
   if ("__throw" in res) {
@@ -28034,7 +28456,13 @@ var WaGateway = class {
           serverPath: this.deps.serverPath,
           // Task 1575 — the gate's owner-self verdict; drives owner attribution
           // for an unbound owner self-phone at the spawn site.
-          ownerSelfPhone: input.ownerSelfPhone
+          ownerSelfPhone: input.ownerSelfPhone,
+          // Task 2234 — the registered-party label, forwarded verbatim so the
+          // spawn env carries WA_SENDER_PARTY. Undefined for every other sender.
+          // Only this call site takes it: the passive branch above hardcodes
+          // role:'admin', and a registered party is public, so the combination
+          // cannot arise there.
+          party: input.party
         });
       } finally {
         this.spawning.delete(senderId);
@@ -30549,7 +30977,7 @@ var waGateway = new WaGateway({
     });
     return result.ok ? { ok: true, messageId: result.messageId } : { ok: false, error: result.error };
   },
-  ensureChannelSession: async ({ accountId, effectiveAccountId, senderId, role, personId, gatewayUrl, serverPath, passive, text, msgId, ownerSelfPhone, replyContext }) => {
+  ensureChannelSession: async ({ accountId, effectiveAccountId, senderId, role, personId, gatewayUrl, serverPath, passive, text, msgId, ownerSelfPhone, replyContext, party }) => {
     warnNonUuidAccount("channel-spawn", effectiveAccountId);
     if (passive) {
       const phoneHash = createHash7("sha256").update(senderId).digest("hex").slice(0, 12);
@@ -30634,7 +31062,7 @@ var waGateway = new WaGateway({
       const sourceSuffix = graphOwnerResolved ? " source=graph-owner" : "";
       console.error(`[whatsapp-native] op=admin-identity senderId=${senderId} userId=${attribution}${sourceSuffix}`);
     }
-    const result = await managerRcSpawn({ ...req, userId });
+    const result = await managerRcSpawn({ ...req, userId, party });
     if ("error" in result) {
       console.error(`[whatsapp-native] spawn-failed senderId=${senderId} role=${role} error=${result.error} status=${result.status}`);
       return;
@@ -32209,6 +32637,7 @@ for (const acct of listValidAccounts()) {
 }
 purgeNonSocketAdminPhonesAtBoot();
 purgeNonSocketAccountManagersAtBoot();
+purgeNonSocketRegisteredPartiesAtBoot();
 void preloadEmbedModel();
 warnOnChannelAdminBindingDrift();
 var bootEnabled = Array.isArray(bootAccountConfig?.enabledPlugins) ? bootAccountConfig.enabledPlugins : [];
@@ -32337,7 +32766,10 @@ init({
         // always captured it and manager.ts assigns it here, but this argument
         // omitted it, so the agent received "this booking" with nothing to
         // resolve it against.
-        replyContext: msg.replyContext
+        replyContext: msg.replyContext,
+        // Task 2234 — the gate's registered-party label, carried to the spawn so
+        // the session env has WA_SENDER_PARTY. Undefined for every other sender.
+        party: msg.party
       });
     } catch (err) {
       console.error(