@agentcomms/whatsapp 0.15.2 → 0.17.0

package/README.md

@@ -11,6 +11,10 @@ npm install -g @agentcomms/whatsapp    # or run it with npx -y @agentcomms/whats
 It needs **macOS with WhatsApp for Mac** installed and signed in, and **Node 22.16 or newer** (it reads with Node's
 own SQLite, which is complete from 22.16; an older Node is refused with what to install).
 
+The local event daemon, [`@agentcomms/events-daemon`](../events-daemon/README.md), may call this package's internal
+read-only event operation over a checked local copy.
+It adds no WhatsApp command or MCP tool, and it cannot send.
+
 ## What it does, and what it never does, in plain words
 
 - **It reads only local files.** Nothing it does to read, search, draft or keep its lists connects to WhatsApp, or

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as paint, A as PATH_OPTIONS, B as colorEnabled, C as checkStorePath, D as CHANNEL_SERVERS, F as approveAndWaitSentence, G as handoffSentence, H as escapeForDisplay, I as approveChangeAtTerminal, J as isCommsError, K as handoffText, L as canPrompt, M as absoluteSearchPath, N as agentMarker, O as CommsError, P as approvalsOf, Q as openCore, R as childEnvironment, S as storeIdentity, T as expandSource, U as exemptFromUpdateGate, V as commandPathOf, W as gatedChangeAtTerminal, X as nameAvailable, Y as lookupName, Z as nameShapeProblem, _ as chatRefOf, a as listChats, at as serverInstallChange, b as requireAccount, c as Presenter, ct as truncateDisplay, d as draftMessage, dt as windowsSystemProgram, et as pathOverridesFromCliOptions, f as Visibility, ft as withFileLock, g as requireSupportedNode, gt as VERSION, h as WhatsAppIndex, i as CHAT_KINDS, it as runCommand, k as EXIT_CODES, l as innerText, lt as updateGateAtTerminal, m as WhatsAppContext, mt as CALLER, n as whatsappStatus, nt as renderPrune, o as readChat, ot as serverPruneChange, p as listKey, pt as writeResult, q as installExitStatus, r as probeStore, rt as resolvePaths, s as searchMessages, t as syncAccount, tt as renderInstall, v as PLATFORM, w as defaultStorePath, x as requireNamedConfig, y as newWhatsAppAccount, z as cliHandoffs } from "./sync-Ce-u-zuv.mjs";
+import { $ as exemptFromUpdateGate, A as requireAccount, B as PATH_OPTIONS, Ct as writeResult, Et as VERSION, F as expandSource, G as approveAndWaitSentence, H as absoluteSearchPath, J as childEnvironment, K as approveChangeAtTerminal, L as CHANNEL_SERVERS, M as storeIdentity, N as checkStorePath, O as PLATFORM, P as defaultStorePath, Q as escapeForDisplay, R as CommsError, S as chatRefOf, St as withFileLock, U as agentMarker, W as approvalsOf, X as colorEnabled, Y as cliHandoffs, Z as commandPathOf, _ as WhatsAppContext, a as CHAT_KINDS, at as lookupName, b as requireSupportedNode, c as searchMessages, ct as openCore, dt as renderInstall, et as gatedChangeAtTerminal, f as draftMessage, ft as renderPrune, gt as serverPruneChange, ht as serverInstallChange, i as probeStore, it as isCommsError, j as requireNamedConfig, k as newWhatsAppAccount, l as Presenter, lt as paint, m as listKey, mt as runCommand, nt as handoffText, o as listChats, ot as nameAvailable, p as Visibility, pt as resolvePaths, q as canPrompt, r as whatsappStatus, rt as installExitStatus, s as readChat, st as nameShapeProblem, t as syncAccount, tt as handoffSentence, u as innerText, ut as pathOverridesFromCliOptions, v as WhatsAppIndex, vt as truncateDisplay, wt as CALLER, xt as windowsSystemProgram, yt as updateGateAtTerminal, z as EXIT_CODES } from "./sync-7LwbofMr.mjs";
 import { rm } from "node:fs/promises";
 import path, { delimiter, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -3582,7 +3582,7 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 		ran = true;
 		exitCode = await runCommand(output(), async () => {
 			requireSupportedNode();
-			await (deps.startMcp ?? (await import("./stdio-entry-Bjqf4Tz2.mjs")).startWhatsAppStdioServer)({
+			await (deps.startMcp ?? (await import("./stdio-entry-ZWI-4ayI.mjs")).startWhatsAppStdioServer)({
 				env,
 				platform,
 				...deps,

package/dist/index.d.mts

@@ -4277,7 +4277,7 @@ declare namespace external_d_exports {
   export { $brand, $input, $output, BRAND, CompileOptions, GlobalMeta, INVALID, Infer$1 as Infer, IssueData, JSONType, NEVER, $RefinementCtx as RefinementCtx, SafeExtendShape, Schema, TimePrecision, TypeOf, ZodAny, ZodArray, ZodBase64, ZodBase64URL, ZodBigInt, ZodBigIntFormat, ZodBoolean, ZodCIDRv4, ZodCIDRv6, ZodCUID, ZodCUID2, ZodCatch, ZodCodec, ZodCoercedBigInt, ZodCoercedBoolean, ZodCoercedDate, ZodCoercedNumber, ZodCoercedString, ZodCompileAsyncError, ZodCompileUnsupportedError, ZodCreditCard, ZodCustom, ZodCustomStringFormat, ZodDate, ZodDefault, ZodDiscriminatedUnion, ZodE164, ZodEmail, ZodEmoji, ZodEnum, ZodError, ZodErrorMap, ZodExactOptional, ZodFile, ZodFirstPartySchemaTypes, ZodFirstPartyTypeKind, ZodFlattenedError, ZodFloat32, ZodFloat64, ZodFormattedError, ZodFunction, ZodGUID, ZodIBAN, ZodIPv4, ZodIPv6, ZodISODate, ZodISODateTime, ZodISODuration, ZodISOTime, ZodInstanceOf, ZodInt, ZodInt32, ZodInt64, ZodIntersection, ZodIssue, ZodIssueCode, ZodJSONSchema, ZodJSONSchemaInternals, ZodJWT, ZodKSUID, ZodLazy, ZodLiteral, ZodMAC, ZodMap, ZodNaN, ZodNanoID, ZodNever, ZodNonOptional, ZodNull, ZodNullable, ZodNumber, ZodNumberFormat, ZodObject, ZodOptional, ZodPipe, ZodPrefault, ZodPreprocess, ZodPromise, ZodRawShape$1 as ZodRawShape, ZodReadonly, ZodRealError, ZodRecord, ZodSafeParseError, ZodSafeParseResult, ZodSafeParseSuccess, ZodSchema, ZodSet, ZodStandardSchemaWithJSON, ZodString, ZodStringFormat, ZodSuccess, ZodSymbol, ZodTemplateLiteral, ZodTransform, ZodTuple, ZodType, ZodTypeAny, ZodUInt32, ZodUInt64, ZodULID, ZodURL, ZodUUID, ZodUndefined, ZodUnion, ZodUnknown, ZodVoid, ZodXID, ZodXor, _ZodBigInt, _ZodBoolean, _ZodDate, _ZodNumber, _ZodString, _ZodType, _default, _function, any, array, base64, base64url, bigint$1 as bigint, boolean$1 as boolean, _catch as catch, check, cidrv4, cidrv6, clone, codec, coerce_d_exports as coerce, compile, config, index_d_exports$1 as core, creditCard, cuid, cuid2, currencyCode, custom, date$2 as date, decode, decodeAsync, deepPartial, describe, discriminatedUnion, e164, email, emoji, encode, encodeAsync, _endsWith as endsWith, _enum as enum, exactOptional, file, flattenError, float32, float64, formatError, fromJSONSchema, _function as function, getDiscriminatedOption, getErrorMap, globalRegistry, _gt as gt, _gte as gte, guid, hash, hex, hostname, httpUrl, iban, _includes as includes, output$1 as infer, inferFlattenedErrors, inferFormattedError, input, _instanceof as instanceof, int, int32, int64, intersection, invertCodec, ipv4, ipv6, iso_d_exports as iso, json, jwt, keyof, ksuid, lazy, _length as length, literal, index_d_exports$2 as locales, looseObject, looseRecord, _lowercase as lowercase, _lt as lt, _lte as lte, mac, map, _maxLength as maxLength, _maxSize as maxSize, memoizer, meta, _mime as mime, _minLength as minLength, _minSize as minSize, _multipleOf as multipleOf, nan, nanoid, nativeEnum, _negative as negative, never, _nonnegative as nonnegative, nonoptional, _nonpositive as nonpositive, _normalize as normalize, _null as null, nullable, nullish, number$1 as number, object, optional, output, _overwrite as overwrite, parse, parseAsync, partialRecord, pipe, _positive as positive, prefault, preprocess, prettifyError, promise, _properties as properties, _property as property, readonly, record, refine, _regex as regex, regexes_d_exports as regexes, registry, safeDecode, safeDecodeAsync, safeEncode, safeEncodeAsync, safeParse, safeParseAsync, set, setErrorMap, _size as size, _slugify as slugify, _startsWith as startsWith, strictObject, string$1 as string, stringFormat, stringbool, success, superRefine, symbol, templateLiteral, toJSONSchema, _toLowerCase as toLowerCase, _toUpperCase as toUpperCase, toZod, transform, treeifyError, _trim as trim, tuple, uint32, uint64, ulid, _undefined as undefined, union, unknown, _uppercase as uppercase, url, util_d_exports as util, uuid, uuidv4, uuidv6, uuidv7, validate, validateAsync, _void as void, withParser, xid, xor };
 }
 //#endregion
-//#region ../core/dist/change-flow-mr6T-6nU.d.mts
+//#region ../core/dist/change-flow-B_bGbrkO.d.mts
 //#region src/config-hooks.d.ts
 /**
  * Test-only pauses inside `ConfigStore.convertToVersion3`, for the tests that prove a write racing the conversion is
@@ -4369,7 +4369,7 @@ interface ResolvedPaths {
    */
   downloadsDir: string;
 }
-type ErrorCode = "UNEXPECTED" | "APPROVAL_REQUIRED" | "APPROVAL_PENDING" | "APPROVAL_EXPIRED" | "APPROVAL_VOID" | "SEND_OUTCOME_UNKNOWN" | "SEND_REFUSED" | "POLICY_NEVER" | "RATE_CAPPED" | "UNSENDABLE_HTML" | "LOOSENING_REFUSED" | "UPDATE_REQUIRED" | "USAGE" | "CURSOR_MISMATCH" | "BAD_DATA" | "REPLY_INVALID" | "NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "SECRET_STORE_UNAVAILABLE" | "TRANSIENT" | "KEYCHAIN_APPROVAL_PENDING" | "LOCK_TIMEOUT" | "AUTH_REQUIRED" | "SCOPE_MISSING" | "CONFIG";
+type ErrorCode = "UNEXPECTED" | "APPROVAL_REQUIRED" | "APPROVAL_PENDING" | "APPROVAL_EXPIRED" | "APPROVAL_VOID" | "SEND_OUTCOME_UNKNOWN" | "SEND_REFUSED" | "POLICY_NEVER" | "RATE_CAPPED" | "UNSENDABLE_HTML" | "LOOSENING_REFUSED" | "UPDATE_REQUIRED" | "USAGE" | "CURSOR_MISMATCH" | "BAD_DATA" | "REPLY_INVALID" | "NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "SOURCE_UNAVAILABLE" | "SECRET_STORE_UNAVAILABLE" | "TRANSIENT" | "KEYCHAIN_APPROVAL_PENDING" | "LOCK_TIMEOUT" | "AUTH_REQUIRED" | "SCOPE_MISSING" | "WHATSAPP_VISIBILITY_SEAM_REQUIRED" | "CONFIG";
 interface CommsErrorOptions {
   hint?: string;
   details?: Record<string, unknown>;
@@ -4999,6 +4999,28 @@ interface LooseningConsent {
  * change's is the live change policy. It never changes when the configuration does.
  */
 type ApprovalRoute = "chat" | "confirm";
+/** The four activation documents that may receive standing disclosure authority. */
+type DisclosureActivationKind = "rule" | "judge-budget" | "judge-kind" | "enable-all";
+/** An immutable version named by a standing disclosure authorisation. */
+type DisclosureVersionKind = "rule" | "target" | "subscriber" | "judge" | "judge-budget" | "judge-kind";
+interface DisclosureVersion {
+  readonly kind: DisclosureVersionKind;
+  readonly id: string;
+  readonly version: number;
+}
+/**
+ * The content-free, canonical authority for a future disclosure (local-event design D2).
+ *
+ * The event daemon derives this from one canonical activation document. Core does not construct
+ * that document; it verifies the closed shape that makes an independently supplied version list
+ * impossible to smuggle into a disclosure record.
+ */
+interface DisclosureBinding {
+  readonly digest: string;
+  readonly activationIntentId: string;
+  readonly activationKind: DisclosureActivationKind;
+  readonly versions: readonly DisclosureVersion[];
+}
 /**
  * What a record's `inboxId` names. `owner` — a mailbox or account that existed when it was made (every send and
  * download, and a change to one). `prospective` — a change that creates its owner, which has no id yet. `global` — a
@@ -5130,7 +5152,10 @@ interface AuditRecord {
   recipients?: string[];
   approvalId?: string;
   reason?: string;
-  surface?: "cli" | "mcp";
+  /** The process that performed the work; daemon work keeps its caller separately in `origin`. */
+  surface?: "cli" | "mcp" | "app" | "daemon";
+  /** The requesting client surface; autonomous work is `daemon`/`daemon`. */
+  origin?: "cli" | "mcp" | "app" | "daemon";
   /**
    * The policy that decided how this was approved. Written by change approvals, where it is the whole question
    * afterwards: a loosening a person typed a code for and one an agent claimed after a yes in chat look the same in
@@ -5250,7 +5275,7 @@ interface CorruptStub {
   readonly reason: UnreadableReason | IntegrityReason;
 }
 /** What an attribution-verified corrupt record may still show its owner: the fields its binding was made over. */
-interface SafeFields {
+interface OrdinarySafeFields {
   readonly kind: ApprovalKind;
   readonly channel: string;
   readonly ownerScope: OwnerScope;
@@ -5260,6 +5285,11 @@ interface SafeFields {
   readonly draftMessageId: string;
   readonly expect: Expectation;
 }
+/** A disclosure record has no channel owner or sender-controlled operational fields to expose. */
+interface DisclosureSafeFields {
+  readonly kind: "disclosure";
+}
+type SafeFields = OrdinarySafeFields | DisclosureSafeFields;
 type StoredApproval = {
   readonly form: "v2";
   readonly record: ApprovalRecord;
@@ -5385,7 +5415,7 @@ type ApprovalChannel = "elicitation" | "terminal";
  * and a kind on every record, so that none can be spent as another. Without it, a person who approved a post at a
  * terminal would also have approved whatever change an agent claimed under the same id.
  */
-type ApprovalKind = "send" | "change" | "download";
+type ApprovalKind = "send" | "change" | "download" | "disclosure";
 /** The inbox or account a change is about. `id` is absent when the change connects it, and it does not exist yet. */
 interface ChangeTarget {
   kind: "inbox" | "account";
@@ -5562,6 +5592,17 @@ interface ApprovalRecord {
   change?: ChangeBinding | undefined;
   /** For a download's question: what it asked about, and the folders it offered. `contentDigest` is `downloadDigest`. */
   download?: DownloadBinding | undefined;
+  /** For a standing disclosure: the canonical, content-free event activation authority. */
+  disclosure?: DisclosureBinding | undefined;
+}
+/**
+ * The stored branch for standing disclosure. Its runtime decoder refuses every field belonging to send, change or
+ * download records; this type is what the three disclosure-only methods return.
+ */
+interface DisclosureApprovalRecord extends Omit<ApprovalRecord, "kind" | "disclosure" | "approvedVia" | "channel" | "ownerScope" | "route" | "inboxId" | "inboxSub" | "draftId" | "draftMessageId" | "contentDigest" | "sendEpoch" | "policy" | "requiredPolicy" | "riskFlags" | "expect" | "approvedBindingDigest" | "sendingAt" | "sendingHeartbeatAt" | "sentAt" | "sentMessageId" | "failedAt" | "change" | "download"> {
+  kind: "disclosure";
+  disclosure: DisclosureBinding;
+  approvedVia?: "terminal" | "app" | undefined;
 }
 interface CreateApprovalInput {
   /** The manifest channel preparing the send. A channel this release does not know is refused. */
@@ -5706,6 +5747,8 @@ declare class ApprovalStore {
    */
   ensurePruned(options?: MaintenanceOptions): Promise<MaintenanceStatus>;
   create(input: CreateApprovalInput): Promise<ApprovalRecord>;
+  /** Creates only a pending standing disclosure approval from a daemon-derived canonical binding. */
+  createDisclosure(binding: DisclosureBinding): Promise<DisclosureApprovalRecord>;
   /**
    * One approval, in whichever of its four forms it is (`StoredApproval`), read against one configuration snapshot —
    * or null when there is none. Nothing is written.
@@ -5748,6 +5791,21 @@ declare class ApprovalStore {
   issueChallenge(approvalId: string, kind?: ApprovalKind, _platform?: NodeJS.Platform, options?: {
     usedSaid?: UsedSaid | undefined;
   }): Promise<string>;
+  /** Issues the typed challenge that a terminal or the trusted desktop app must answer for disclosure. */
+  issueDisclosureChallenge(approvalId: string): Promise<string>;
+  /**
+   * Approves one exact standing disclosure authority. MCP/chat forms are never an approval channel here: `app` means
+   * the desktop application's trusted typed-challenge bridge, not a client form.
+   */
+  approveDisclosure(approvalId: string, liveBinding: DisclosureBinding, answer: string, via: "terminal" | "app"): Promise<DisclosureApprovalRecord>;
+  /**
+   * Claims an approved disclosure once, persisting the exact `usedAt` that recovery must subsequently reuse.
+   * A specialised caller may impose a shorter deadline; it is evaluated while this record's transition lock is held,
+   * so a check made before waiting on that lock cannot accidentally consume the approval after it has expired.
+   */
+  claimForDisclosure(approvalId: string, liveBinding: DisclosureBinding, options?: {
+    readonly deadlineMs?: number | undefined;
+  }): Promise<DisclosureApprovalRecord>;
   /**
    * A human approved through a confirm channel by typing the issued challenge. The draft must still be exactly what the
    * record was prepared for; otherwise the record is voided, because the human would be approving content the record
@@ -6069,9 +6127,13 @@ interface TaintHandle {
   id: string;
 }
 type TaintSource = "header" | "body";
+/** Why the content reached this process. This is separate from `TaintSource`, which remains the cap priority. */
+type TaintOrigin = "read" | "event";
 interface TaintObservation {
   address: string;
   source: TaintSource;
+  /** Old readers did not record this, so an omitted origin remains an ordinary read. */
+  origin?: TaintOrigin | undefined;
   inboxId: string;
   messageId?: string | undefined;
 }
@@ -6079,6 +6141,8 @@ interface TaintObservation {
 interface TaintHandleObservation {
   handle: TaintHandle;
   source: TaintSource;
+  /** Old readers did not record this, so an omitted origin remains an ordinary read. */
+  origin?: TaintOrigin | undefined;
   inboxId: string;
   messageId?: string | undefined;
 }
@@ -6102,6 +6166,8 @@ interface TaintAggregate {
   readonly at: string;
   readonly source: TaintSource;
   readonly inboxIds: readonly string[];
+  /** Sorted, duplicate-free provenance. A base entry with no sidecar record is a legacy read. */
+  readonly origins: readonly TaintOrigin[];
 }
 interface TaintCheck {
   address: boolean;
@@ -6111,10 +6177,15 @@ interface TaintCheck {
   /** Its domain's, when that counts — not a public mailbox provider — and is in the window. */
   domainSeen?: TaintAggregate | undefined;
 }
+/** Testable interruption point for the crash-safe, two-lock sidecar protocol. */
+interface TaintStoreHooks {
+  afterOriginsCommit?: (() => Promise<void>) | undefined;
+  onLockAcquired?: ((lock: "origins" | "taint" | "handles") => void) | undefined;
+}
 declare class TaintStore {
   #private;
   readonly directory: string;
-  constructor(stateDir: string, now?: () => Date);
+  constructor(stateDir: string, now?: () => Date, hooks?: TaintStoreHooks);
   /**
    * Records observations. Throws if it cannot — callers must fail the read rather than return content whose taint
    * was not recorded.
@@ -6132,6 +6203,8 @@ declare class TaintStore {
    * carries a domain: two ids sharing a workspace says nothing about either of them.
    */
   checkHandle(handle: TaintHandle): Promise<boolean>;
+  /** The merged provenance of a retained handle, or no origins when it is not in the taint window. */
+  checkHandleOrigins(handle: TaintHandle): Promise<readonly TaintOrigin[]>;
 }
 //#endregion
 //#region src/core.d.ts
@@ -13349,9 +13422,121 @@ type RegisteredPrompt = {
   remove(): void;
 };
 //#endregion
+//#region src/config.d.ts
+interface WhatsAppAccount extends AccountConfig {
+  /** The store, when it is not WhatsApp for Mac's default. Absent means the default. */
+  source?: string | undefined;
+}
+//#endregion
 //#region src/source/types.d.ts
+/**
+ * What a `ZWAMESSAGE.ZMESSAGETYPE` number means.
+ *
+ * From [F] and [W] in `schema.ts` — two independent public tables that agree where they overlap — with [I] for 5 and
+ * [K] for 6, 14 and 15. iLEAPP says plainly that it has no source for the rest; neither has this. A number not listed
+ * is reported as `unknown` with the number, never guessed at.
+ */
+type MessageKind = "text" | "image" | "video" | "audio" | "contact" | "location" | "group-event" | "link" | "document" | "system" | "gif" | "waiting" | "deleted" | "sticker" | "poll" | "video-note" | "call" | "album" | "unknown";
 /** What a chat is, from its JID — the one part of a chat WhatsApp assigns and nobody in it can choose. */
 type ChatKind = "direct" | "hidden-number" | "group" | "status" | "broadcast" | "channel" | "unknown";
+/**
+ * [M] imports exactly three kinds of conversation — `@s.whatsapp.net`, `@lid` and `@g.us` — and skips every other
+ * session, comparing JIDs lower-cased; [I] names `@newsletter` chats as channels. The rest were seen rather than
+ * sourced: a real store kept each contact's status posts in a session of its own, `<number>@status`, and WhatsApp's
+ * own status feed and broadcast lists use `status@broadcast` and `<id>@broadcast`. A JID none of these match is
+ * `unknown`, never guessed at.
+ */
+export declare function chatKindOf(jid: string): ChatKind;
+//#endregion
+//#region src/visibility.d.ts
+/**
+ * Which chats an agent may see in an account: the person's allow and deny lists.
+ *
+ * - **deny**: chats an agent must never see. A denied chat is not listed, searched, read, counted or drafted to, and
+ *   asking for it by id gets the answer a chat that does not exist gets.
+ * - **allow**: when it has anything on it, the only chats an agent may see.
+ * - Denied wins over allowed. With neither list, every chat is visible — status updates are still left out of
+ *   listings and searches unless asked for, which is a default, not a list.
+ *
+ * An entry is a chat id, or a phone number kept as its `…@s.whatsapp.net` id. A number names a person rather than one
+ * chat: their one-to-one chat and their own status posts (`<number>@status`) — and, in a status feed, where each post
+ * is its author's, the posts they wrote.
+ *
+ * **A status post needs an author the lists can be checked against.** Its author is the person WhatsApp recorded as
+ * sending it, or — in a contact's own `<number>@status` session — that contact; one the person posted is theirs. A post
+ * with no author (no `ZFROMJID`, no group-member row, or an id that names no person) could be anyone's, including
+ * someone denied, so it is shown only while the lists hide nobody, and otherwise hidden and counted
+ * (`unattributed`). Failing closed costs posts nobody can be named for; failing open showed a denied person's.
+ *
+ * **A group is a chat**, allowed or denied whole: denying someone does not remove what they wrote in a group the agent
+ * may see, whether WhatsApp recorded them as its author or not — so an unknown author in a group hides nothing either.
+ * A status post is its author's alone, and a feed only files them together. A group message is part of a conversation
+ * the others answer and quote, so hiding one person's lines would leave the rest describing them. It could not be
+ * done reliably either: a member can appear under a hidden-number id (`…@lid`) that their number does not match, and
+ * an allowed group would lose every member not on the allow list. Denying the group is what hides it.
+ *
+ * Every read applies this — `WhatsAppIndex` cannot be opened without one — and so does `sync`, which leaves what it
+ * hides out of the index, so a hidden chat's messages are not kept in a second copy on disk either.
+ */
+interface ChatLists {
+  readonly allow: readonly string[];
+  readonly deny: readonly string[];
+}
+/** One entry per person or chat: a phone number and the ids that carry it compare equal. */
+export declare function listKey(jid: string): string;
+/**
+ * The one visibility unit a raw row belongs to.  The daemon persists this key, but only this channel defines the
+ * vocabulary: an ordinary chat is its list key; a status post is the pair of its status chat and its author (or no
+ * author), because the lists can hide either one — denying the status feed hides every author in it.
+ */
+export declare function visibilityUnitKey(chatId: string, chatKind: ChatKind | string, senderJid: string | null): string;
+export declare class Visibility {
+  #private;
+  constructor(lists: ChatLists | undefined);
+  /** Whether an agent may see this chat at all. */
+  seesChat(chatId: string): boolean;
+  /**
+   * Whether an agent may see this message: its chat must be visible, and in a status chat, its author — the person's
+   * own posts always, anyone else's only when they are known and visible, or when the lists hide nobody at all.
+   */
+  seesMessage(chatId: string, chatKind: ChatKind | string, senderJid: string | null, fromMe: boolean): boolean;
+  /** Whether a durable source unit remains visible under these same lists. */
+  seesUnit(unitKey: string): boolean;
+  /** A status post someone else wrote with no author the lists can be checked against: hidden while they hide anyone. */
+  unattributed(chatId: string, chatKind: ChatKind | string, senderJid: string | null, fromMe: boolean): boolean;
+}
+/**
+ * Who wrote a status post, as an id the lists can be checked against — or null when nobody can be named.
+ *
+ * The sender WhatsApp recorded, when it is a person (a number, or a hidden number); otherwise, in a contact's own
+ * session, that contact. A group's, a feed's or a broadcast's id is no author.
+ */
+export declare function statusAuthor(chatId: string, senderJid: string | null): string | null;
+//#endregion
+//#region src/lists.d.ts
+declare class ChatListStore {
+  #private;
+  readonly path: string;
+  constructor(configDir: string);
+  /** One account's lists; none when the account has no entry. */
+  of(accountId: string): Promise<ChatLists>;
+  /**
+   * Reads the live list while holding the same inter-process gate as allow/deny/clear.  Event consumers get the
+   * parsed policy and its canonical digest, never a second mutable copy of the list file.
+   */
+  withCurrent<T>(accountId: string, work: (current: Readonly<{
+    version: 1;
+    lists: ChatLists;
+    digest: string;
+  }>) => Promise<T> | T): Promise<T>;
+  /** Changes one account's lists under the file's lock; an account left with neither list has no entry. */
+  update(accountId: string, change: (lists: ChatLists) => ChatLists): Promise<{
+    before: ChatLists;
+    after: ChatLists;
+  }>;
+  /** Forgets an account's lists: when the account is removed. */
+  forget(accountId: string): Promise<void>;
+}
 //#endregion
 //#region src/source/snapshot.d.ts
 /**
@@ -13409,6 +13594,43 @@ interface SourceIo {
   /** Opens a file read-only, refusing a link and never waiting on a pipe. */
   open(path: string): Promise<SourceHandle>;
 }
+interface SourceOptions {
+  /**
+   * What a refusal names to run — `status` at a terminal, an `add` for another store — located as the package printing
+   * it finds its own command (`WhatsAppContext.handoffs`). Required: there is no bare `agent-whatsapp` to fall back on.
+   */
+  handoffs: CliHandoffs;
+  io?: SourceIo | undefined;
+  env?: NodeJS.ProcessEnv | undefined;
+  platform?: NodeJS.Platform | undefined;
+  timeoutMs?: number | undefined;
+  /** Copies attempted before a store that keeps changing is refused. */
+  attempts?: number | undefined;
+  sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** The account's default store, so "not found" can say WhatsApp may not be installed rather than blame a path. */
+  isDefault?: boolean | undefined;
+}
+//#endregion
+//#region src/spike-migration.d.ts
+interface SpikeMigration {
+  /** Moved into `config.json` by this run. */
+  migrated: string[];
+  /** Already there, by id, from an earlier run that stopped before it could put the file aside. */
+  alreadyThere: string[];
+  /**
+   * Left in the old file, with why — and, when the spike built one for it, where its index still is: a plaintext copy
+   * of its messages that no account reads now and no command deletes.
+   */
+  skipped: {
+    name: string;
+    reason: string;
+    index?: string | undefined;
+  }[];
+  /** Where the old file went, or null when it stayed because nothing could be moved yet (`deferred`). */
+  keptAs: string | null;
+  /** Why nothing moved at all, when nothing could. */
+  deferred?: string | undefined;
+}
 //#endregion
 //#region src/context.d.ts
 /**
@@ -13443,6 +13665,58 @@ interface WhatsAppContextOptions {
   sourceTimeoutMs?: number | undefined;
   platform?: NodeJS.Platform | undefined;
 }
+interface ResolvedAccount {
+  name: string;
+  account: WhatsAppAccount;
+  lists: ChatLists;
+}
+declare class WhatsAppContext {
+  #private;
+  readonly env: NodeJS.ProcessEnv;
+  readonly now: () => Date;
+  readonly surface: "cli" | "mcp";
+  readonly platform: NodeJS.Platform;
+  readonly core: Core;
+  /** The commands this tells a person to run, located, and quoted for this context's shell. */
+  readonly handoffs: CliHandoffs;
+  readonly lists: ChatListStore;
+  /** The name a pinned server was started for, as given. */
+  readonly pinned: string | undefined;
+  constructor(options?: WhatsAppContextOptions);
+  /** The spike's accounts moved in, once per process; what happened, when there was a spike file to move. */
+  migration(): Promise<SpikeMigration | null>;
+  /** core's configuration, after the spike's accounts have moved into it. */
+  config(): Promise<Config$1>;
+  /**
+   * The server's pin, checked to name a WhatsApp account, and remembered by its id.
+   *
+   * By id, as Slack's server does, because a rename can move the name under a running server: the pin follows the
+   * account, and a new account that took the name afterwards is not one anybody pinned this server to.
+   */
+  checkPin(): Promise<void>;
+  /** One account, resolved and checked, with the person's lists for it — which every read applies. */
+  account(named: string | undefined): Promise<ResolvedAccount>;
+  /** The accounts a call without one covers: every WhatsApp account, or the pinned one alone. */
+  accountNames(): Promise<string[]>;
+  /** Where an account's store is, and whether that is the WhatsApp for Mac default. */
+  storeOf(account: WhatsAppAccount): {
+    path: string;
+    isDefault: boolean;
+  };
+  sourceOptions(isDefault: boolean): SourceOptions;
+  /** The account's own directory under core's state directory: its index and its brief snapshots. */
+  accountDir(account: WhatsAppAccount): string;
+  /**
+   * The lock a sync and a remove of this account both hold, so neither runs while the other does. Beside the
+   * account's directory rather than in it, because a remove deletes the directory while it holds the lock.
+   */
+  syncLock(account: WhatsAppAccount): string;
+  /**
+   * The account with this id as it is now, under whatever name it has now, with its lists as they are now — or null
+   * when it is gone. For a sync to look again, under its lock, at what it started with.
+   */
+  accountById(id: string): Promise<ResolvedAccount | null>;
+}
 //#endregion
 //#region src/mcp/server.d.ts
 /**
@@ -13495,4 +13769,67 @@ export declare function composeDraft(request: {
   text: string;
 }): DraftResult;
 //#endregion
-export type { DraftResult, WhatsAppMcpOptions, WhatsAppMcpServer };
+//#region src/source/event-reader.d.ts
+/**
+ * The event reader deliberately keeps the source tuple before the presentation index derives sender information.
+ * A row-id is available only to produce a stable checked-copy read order; it is never returned as identity.
+ */
+interface RawEventMessage {
+  readonly sourceOrder: number;
+  readonly chatJid: string | null;
+  readonly chatKind: ChatKind | null;
+  readonly senderJidRaw: string | null;
+  readonly stanzaId: string | null;
+  /** Exactly false is eligible. A malformed, absent, or non-boolean Core Data value remains unknown. */
+  readonly fromMe: boolean | null;
+  readonly at: string | null;
+  readonly kind: MessageKind;
+  readonly body: string | null;
+}
+//#endregion
+//#region src/operations/events.d.ts
+/**
+ * The held event owner receives this deliberately narrow, read-only operation object.  In particular it never
+ * exposes ChatListStore, whose update/forget methods are local list writes rather than event-reader capabilities.
+ */
+interface WhatsAppEventOperations {
+  withCurrentEventVisibility<T>(input: Readonly<{
+    accountId: string;
+  }>, work: (visibility: CurrentEventVisibility) => Promise<T> | T): Promise<T>;
+  withEventSnapshot<T>(input: Readonly<{
+    accountId: string;
+  }>, work: (snapshot: EventSnapshot) => Promise<T> | T): Promise<T>;
+}
+/** Opens this channel's own context from the owner's config directory and returns no write-capable local-store handle. */
+export declare function openWhatsAppEventOperations(input: Readonly<{
+  configDir: string;
+}>): WhatsAppEventOperations;
+interface CurrentEventVisibility {
+  /** The list-file format version, not the daemon's durable journal version. */
+  readonly version: 1;
+  readonly digest: string;
+  readonly seesMessage: (chatJid: string, chatKind: string, senderJidRaw: string, fromMe: boolean) => boolean;
+  readonly seesUnit?: ((unitKey: string) => boolean) | undefined;
+}
+interface EventSnapshot {
+  readonly accountId: string;
+  readonly accountName: string;
+  readonly visibility: CurrentEventVisibility;
+  readonly messages: readonly RawEventMessage[];
+}
+/**
+ * The channel's live-list capability boundary.  The callback runs while `.whatsapp-chats.lock` is held, so a daemon
+ * may place a synchronous SQLite decision immediately after this read without a list command racing it.
+ */
+export declare function withCurrentEventVisibility<T>(context: WhatsAppContext, input: Readonly<{
+  accountId: string;
+}>, work: (visibility: CurrentEventVisibility) => Promise<T> | T): Promise<T>;
+/**
+ * Runs the checked-copy lifecycle for the event source.  The normal index is rebuilt first, but the source copies
+ * only raw values from the checked copy and never observes the rebuilt index.
+ */
+export declare function withEventSnapshot<T>(context: WhatsAppContext, input: Readonly<{
+  accountId: string;
+}>, work: (snapshot: EventSnapshot) => Promise<T> | T): Promise<T>;
+//#endregion
+export type { ChatKind, CurrentEventVisibility, DraftResult, EventSnapshot, RawEventMessage, WhatsAppEventOperations, WhatsAppMcpOptions, WhatsAppMcpServer };

package/dist/index.mjs

@@ -1,11 +1,96 @@
-import { gt as VERSION, ht as PACKAGE_NAME, u as composeDraft } from "./sync-Ce-u-zuv.mjs";
-import { t as createWhatsAppMcpServer } from "./server-DFGzE4pA.mjs";
+import { C as chatKindOf, D as text, E as numeric, Et as VERSION, R as CommsError, T as kindOf, Tt as PACKAGE_NAME, _ as WhatsAppContext, d as composeDraft, g as visibilityUnitKey, h as statusAuthor, m as listKey, n as withCheckedCopy, p as Visibility, w as coreDataToIso, x as inspectSchema, y as rebuildIndex } from "./sync-7LwbofMr.mjs";
+import { t as createWhatsAppMcpServer } from "./server-DChdfrt8.mjs";
+//#region src/source/event-reader.ts
+function rawFromMe(value) {
+	const number = numeric(value);
+	if (number === 0) return false;
+	if (number === 1) return true;
+	return null;
+}
+/**
+* Reads only raw, checked-copy facts needed by the local event source.  It intentionally does not call
+* `rebuildIndex`, `WhatsAppIndex`, or any presentation sender fallback.
+*/
+function readRawEventMessages(database, _report) {
+	return database.prepare(`SELECT m.Z_PK AS sourceOrder, c.ZCONTACTJID AS chatJid, m.ZFROMJID AS senderJidRaw,
+              m.ZSTANZAID AS stanzaId, m.ZISFROMME AS fromMe, m.ZMESSAGEDATE AS at,
+              m.ZMESSAGETYPE AS typeCode, m.ZTEXT AS body
+         FROM ZWAMESSAGE AS m
+         LEFT JOIN ZWACHATSESSION AS c ON c.Z_PK = m.ZCHATSESSION
+        ORDER BY m.Z_PK`).all().map((row) => {
+		const chatJid = text(row.chatJid) || null;
+		const type = numeric(row.typeCode);
+		return {
+			sourceOrder: numeric(row.sourceOrder) ?? 0,
+			chatJid,
+			chatKind: chatJid === null ? null : chatKindOf(chatJid),
+			senderJidRaw: text(row.senderJidRaw) || null,
+			stanzaId: text(row.stanzaId) || null,
+			fromMe: rawFromMe(row.fromMe),
+			at: coreDataToIso(numeric(row.at)),
+			kind: kindOf(type).kind,
+			body: text(row.body)
+		};
+	});
+}
+//#endregion
+//#region src/operations/events.ts
+/** Opens this channel's own context from the owner's config directory and returns no write-capable local-store handle. */
+function openWhatsAppEventOperations(input) {
+	const context = new WhatsAppContext({ pathOverrides: { configDir: input.configDir } });
+	return {
+		withCurrentEventVisibility: (visibilityInput, work) => withCurrentEventVisibility(context, visibilityInput, work),
+		withEventSnapshot: (snapshotInput, work) => withEventSnapshot(context, snapshotInput, work)
+	};
+}
+/**
+* The channel's live-list capability boundary.  The callback runs while `.whatsapp-chats.lock` is held, so a daemon
+* may place a synchronous SQLite decision immediately after this read without a list command racing it.
+*/
+async function withCurrentEventVisibility(context, input, work) {
+	return context.lists.withCurrent(input.accountId, async ({ version, lists, digest }) => {
+		const visibility = new Visibility(lists);
+		return work({
+			version,
+			digest,
+			seesMessage: (chatJid, chatKind, senderJidRaw, fromMe) => visibility.seesMessage(chatJid, chatKind, senderJidRaw, fromMe),
+			seesUnit: (unitKey) => visibility.seesUnit(unitKey)
+		});
+	});
+}
+/**
+* Runs the checked-copy lifecycle for the event source.  The normal index is rebuilt first, but the source copies
+* only raw values from the checked copy and never observes the rebuilt index.
+*/
+async function withEventSnapshot(context, input, work) {
+	return withCheckedCopy(context, input, async ({ account, accountName, directory, database, snapshot }) => {
+		const report = inspectSchema(database);
+		const current = await context.accountById(account.id);
+		if (current === null) throw new CommsError("NOT_FOUND", "the account was removed while its event snapshot was being read");
+		await rebuildIndex(directory, database, report, {
+			indexedAt: context.now().toISOString(),
+			copied: snapshot.copied
+		}, new Visibility(current.lists), async () => {
+			const latest = await context.accountById(account.id);
+			return latest !== null && JSON.stringify(latest.lists) === JSON.stringify(current.lists);
+		});
+		if (await context.accountById(account.id) === null) throw new CommsError("NOT_FOUND", "the account was removed while its event snapshot was being read");
+		const messages = readRawEventMessages(database, report).filter((message) => (message.fromMe === false || message.fromMe === true) && message.chatJid !== null && message.chatKind !== null);
+		return withCurrentEventVisibility(context, { accountId: account.id }, (visibility) => work({
+			accountId: account.id,
+			accountName,
+			visibility,
+			messages
+		}));
+	});
+}
+//#endregion
 //#region src/index.ts
 /**
 * The library entry of `@agentcomms/whatsapp`.
 *
-* Small on purpose, as the Slack package's is: the server, the draft composer and the version. Everything else is
-* reached through the `agent-whatsapp` command.
+* Small on purpose, as the Slack package's is: the server, the draft composer, the event list-lock capability and the
+* version. Everything else is reached through the `agent-whatsapp` command.
 */
 //#endregion
-export { PACKAGE_NAME, VERSION, composeDraft, createWhatsAppMcpServer };
+export { PACKAGE_NAME, VERSION, Visibility, chatKindOf, composeDraft, createWhatsAppMcpServer, listKey, openWhatsAppEventOperations, statusAuthor, visibilityUnitKey, withCurrentEventVisibility, withEventSnapshot };

package/dist/{server-DFGzE4pA.mjs → server-DChdfrt8.mjs}

@@ -1,4 +1,4 @@
-import { E as strictToolArguments, a as listChats, d as draftMessage, gt as VERSION, i as CHAT_KINDS, j as UNTRUSTED_NOTICE, m as WhatsAppContext, n as whatsappStatus, o as readChat, s as searchMessages, st as toCommsError, t as syncAccount, ut as updateToolGate } from "./sync-Ce-u-zuv.mjs";
+import { Et as VERSION, I as strictToolArguments, V as UNTRUSTED_NOTICE, _ as WhatsAppContext, _t as toCommsError, a as CHAT_KINDS, bt as updateToolGate, c as searchMessages, f as draftMessage, o as listChats, r as whatsappStatus, s as readChat, t as syncAccount } from "./sync-7LwbofMr.mjs";
 import { c as boolean, h as number, x as string } from "./iso-USuVU_sk.mjs";
 import { t as McpServer } from "./mcp-DXXb3Vv3-kCxsVLO4.mjs";
 //#region src/mcp/server.ts

package/dist/{stdio-entry-Bjqf4Tz2.mjs → stdio-entry-ZWI-4ayI.mjs}

@@ -1,4 +1,4 @@
-import { t as createWhatsAppMcpServer } from "./server-DFGzE4pA.mjs";
+import { t as createWhatsAppMcpServer } from "./server-DChdfrt8.mjs";
 //#region src/mcp/stdio-entry.ts
 /**
 * Starting the stdio server. On stdio, stdout is the protocol, so the console is redirected to stderr first — the