@cotal-ai/core 0.84.0 → 0.86.0

package/dist/endpoint.js

@@ -29,6 +29,8 @@ import { openAclRegistry, readAcl, readAclForAlias, aclRetired, AmbiguousAclAlia
 import { openDeliveryRegistry } from "./lease.js";
 import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, effectiveDeliveryClass, readChannelConfig, readChannelDefaults, decodeChannelEntry, } from "./channels.js";
 import { anycastSubject, assertValidRole, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, controlServiceSubject, livenessSubject, livenessServeFilter, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, MANAGER_RENEWAL_LEASE_KEY, managerLeaseKey, chatWildcard, assertValidChannel, channelInAllow, isConcreteChannel, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
+import { isPermissionDenied } from "./permission-denied.js";
+export { isPermissionDenied };
 export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
 const PLANE3_FRAME_HEADER = "Cotal-Delivery-Frame";
 /** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
@@ -178,6 +180,14 @@ export class CotalEndpoint extends EventEmitter {
      *  live iterator. See {@link watchDeliveryLease}. */
     leaseWatchIntent;
     leaseWatchIter;
+    /** Consumer deletes of retired lease watches still in flight. The stop handle cannot await its
+     *  delete, so {@link stop} and a live-epoch rebuild await these before they close the connection
+     *  that carries them (#3966). */
+    leaseWatchDeletes = new Set();
+    /** Lease-watch binds still awaiting the broker. One that lands after {@link stop} or a rebuild
+     *  moved the epoch retires its watch and starts that delete itself, so the same two paths wait for
+     *  these first. Each is bounded by the JetStream request timeout. */
+    leaseWatchBinds = new Set();
     /** Plane-3 durable-membership registry KV — lazily opened by the privileged delivery daemon (or a
      *  short-lived provisioner). */
     membersKv;
@@ -294,9 +304,10 @@ export class CotalEndpoint extends EventEmitter {
     presenceViewState = "unpopulated";
     /** A presence-watch rebind in flight (see {@link rebindStalePresenceWatch}); one at a time. */
     presenceRebind;
-    /** Bumped by every connection-scoped teardown and by {@link stop}. A presence bind that was
-     *  awaiting the broker when the epoch moved belongs to a retired epoch: it releases the
-     *  iterator it got and installs nothing (see {@link startPresenceWatch}). */
+    /** Bumped by every connection-scoped teardown and by {@link stop}. A presence or lease-watch bind
+     *  that was awaiting the broker when the epoch moved belongs to a retired epoch: it releases the
+     *  iterator it got and installs nothing (see {@link startPresenceWatch} and
+     *  {@link bindDeliveryLeaseWatch}). */
     presenceEpoch = 0;
     /** The current watch was bound onto a bucket with NO keys (see {@link markPresenceBucketEmpty}).
      *  Such a watch cannot deliver until someone writes, so its silence is not staleness. */
@@ -1087,9 +1098,9 @@ export class CotalEndpoint extends EventEmitter {
                 await this.startChannelWatch();
         }
         // Rebind the daemon's lease-loss watch onto the fresh connection (#1596). The intent survived
-        // clearConnectionScoped; a bind that completes after a stop or another rebuild found no intent
-        // and released itself. The replay re-delivers the row's current state, so a change that landed
-        // in the null window still reaches the trigger.
+        // clearConnectionScoped; a bind that completes after a stop or another rebuild finds the epoch
+        // moved and retires itself. The replay re-delivers the row's current state, so a change that
+        // landed in the null window still reaches the trigger.
         if (this.leaseWatchIntent)
             await this.bindDeliveryLeaseWatch();
         // FAIL BEFORE PRESENCE (SPEC 13.1): an AUTHED endpoint that will register on the roster or
@@ -1432,7 +1443,7 @@ export class CotalEndpoint extends EventEmitter {
             // Manual reconnect still has a live old epoch: complete broker-consumer cleanup before close.
             // Terminal self-heal has an already-closed epoch: disarm retains stream/name for fresh cleanup.
             if (oldNc && !oldNc.isClosed())
-                await Promise.all([...this.membershipFeedWatches].map((watch) => watch.arm));
+                await Promise.all([...[...this.membershipFeedWatches].map((watch) => watch.arm), this.settleDeliveryLeaseWatches()]);
             this.nc = undefined;
             this.js = undefined;
             this.jsm = undefined;
@@ -1629,6 +1640,7 @@ export class CotalEndpoint extends EventEmitter {
         catch {
             /* best-effort graceful leave */
         }
+        await this.settleDeliveryLeaseWatches();
         await this.closeWithoutLibraryReconnect(this.nc);
         // #1356: stop() does its own teardown and never runs clearConnectionScoped, so clear here too —
         // AFTER the best-effort offline publish above, which would otherwise re-record a refusal on its
@@ -2397,6 +2409,18 @@ export class CotalEndpoint extends EventEmitter {
         this.card.meta = meta;
         await this.publishPresence();
     }
+    /** Overlay the session's working directory onto the card's display-only `meta.cwd`, then
+     *  republish presence. For connectors that learn the directory from the harness after launch (e.g.
+     *  Claude Code's `SessionStart` hook) rather than from their own process. Advisory display data,
+     *  never a routing or access input. The pathname is kept byte for byte: a directory name may hold
+     *  or end in whitespace, so it is never trimmed or normalized. An empty string names no directory
+     *  and leaves the card unchanged. */
+    async setCardCwd(cwd) {
+        if (!cwd || this.card.meta?.cwd === cwd)
+            return;
+        this.card.meta = { ...(this.card.meta ?? {}), cwd };
+        await this.publishPresence();
+    }
     // ---- channel discovery ---------------------------------------------------
     /** This channel's registry config from the live local cache (undefined if unset). */
     getChannelConfig(channel) {
@@ -2677,8 +2701,6 @@ export class CotalEndpoint extends EventEmitter {
                 watch.arm = watch.arm.catch(() => { }).then(async () => {
                     await this.disarmMembershipWatch(watch);
                     await this.deleteRetainedMembershipConsumer(watch);
-                    if (watch.consumerStream || watch.consumerName)
-                        return;
                     this.finishMembershipWatchStop(watch);
                 }).catch((err) => {
                     // A real authorization/server failure remains loud. A terminal close is retained rather than
@@ -2772,10 +2794,10 @@ export class CotalEndpoint extends EventEmitter {
         const cut = subject.lastIndexOf("_") + 1;
         return /^\d+$/.test(subject.slice(cut)) && this.ownWatchDeletePrefixes.has(subject.slice(0, cut));
     }
-    /** Delete a history reader's own ephemeral consumer. A refused delete is the designed outcome for
-     *  the elevated profile, which holds no stream-wide CONSUMER.DELETE (#691): the broker reaps the
-     *  consumer at its inactive threshold. */
-    async deleteReaderConsumer(consumer) {
+    /** Delete one of this connection's own ephemeral consumers, a history reader's or a KV watch's. A
+     *  refused delete is the designed outcome for a profile without a stream-wide CONSUMER.DELETE
+     *  (#691): the broker reaps the consumer at its inactive threshold. */
+    async deleteOwnConsumer(consumer) {
         try {
             await consumer.delete();
         }
@@ -3185,7 +3207,7 @@ export class CotalEndpoint extends EventEmitter {
             throw new Error(`history: the broker reported messages on ${subjectLabel(subjects)} but delivered none - the read was cut short, not empty`);
         }
         finally {
-            await this.deleteReaderConsumer(consumer);
+            await this.deleteOwnConsumer(consumer);
         }
     }
     /** The newest stream sequence matching `subject`, or 0 when the subject has no messages.
@@ -3225,7 +3247,7 @@ export class CotalEndpoint extends EventEmitter {
             throw new Error(`history: the broker reported messages on ${subjectLabel(subjects)} but delivered none - the read was cut short, not empty`);
         }
         finally {
-            await this.deleteReaderConsumer(consumer);
+            await this.deleteOwnConsumer(consumer);
         }
     }
     /** Drain every message matching `subject` with sequence in `[start, ceiling]`, oldest-first.
@@ -3302,7 +3324,7 @@ export class CotalEndpoint extends EventEmitter {
             // resulting resource exhaustion would land in streamHistory's catch and read as empty history.
             // The observer and admin profiles may not delete (#691), so the dashboard's readers do live out
             // that threshold; only a profile holding the delete row reclaims them here.
-            await this.deleteReaderConsumer(consumer).finally(() => { this.ownWatchDeletePrefixes.delete(readerPrefix); });
+            await this.deleteOwnConsumer(consumer).finally(() => { this.ownWatchDeletePrefixes.delete(readerPrefix); });
         }
     }
     // ---- internals -----------------------------------------------------------
@@ -3700,20 +3722,49 @@ export class CotalEndpoint extends EventEmitter {
         };
     }
     stopDeliveryLeaseWatch() {
+        if (this.leaseWatchIter)
+            this.retireDeliveryLeaseWatch(this.leaseWatchIter);
+        this.leaseWatchIter = undefined;
+    }
+    /** Stop a lease watch and delete its ordered consumer, which the stop alone leaves on the broker
+     *  until its five-minute inactive threshold (#3966). A connection that closed on its own cannot
+     *  carry the delete, so that consumer is left to the threshold. A failed delete is a warning: the
+     *  broker still reaps the consumer, and the daemon's synchronous stop handle has no caller to
+     *  reject. */
+    retireDeliveryLeaseWatch(iter) {
         try {
-            this.leaseWatchIter?.stop();
+            iter.stop();
         }
         catch { /* already closed with its connection */ }
-        this.leaseWatchIter = undefined;
-    }
-    async bindDeliveryLeaseWatch() {
+        if (!this.nc || this.nc.isClosed())
+            return;
+        const deleting = this.deleteOwnConsumer(kvWatchConsumer(iter)).catch((e) => this.emitRecoverable(new Error(`a retired delivery lease watch consumer was not deleted (${e.message}); the broker reaps it at its inactive threshold`)));
+        this.leaseWatchDeletes.add(deleting);
+        void deleting.then(() => this.leaseWatchDeletes.delete(deleting));
+    }
+    /** Wait for the lease-watch binds still in flight, then for every retired watch's consumer delete.
+     *  {@link stop} and a live-epoch rebuild run this before they close the connection those deletes
+     *  need (#3966). */
+    async settleDeliveryLeaseWatches() {
+        await Promise.allSettled(this.leaseWatchBinds);
+        await Promise.all(this.leaseWatchDeletes);
+    }
+    /** Bind the lease watch on the current connection. A bind that lands after a newer watch replaced
+     *  its intent, or after a stop or connection teardown moved the epoch, retires its watch instead of
+     *  installing it: the epoch it was bound for is gone, and a rebuilt one binds its own. */
+    bindDeliveryLeaseWatch() {
+        const binding = this.bindDeliveryLeaseWatchOnce();
+        const settled = () => { this.leaseWatchBinds.delete(binding); };
+        this.leaseWatchBinds.add(binding);
+        void binding.then(settled, settled);
+        return binding;
+    }
+    async bindDeliveryLeaseWatchOnce() {
         const intent = this.leaseWatchIntent;
+        const epoch = this.presenceEpoch;
         const iter = await (await this.deliveryRegistry()).watch({ key: leaseKey(intent.shardIndex) });
-        if (this.leaseWatchIntent !== intent) {
-            try {
-                iter.stop();
-            }
-            catch { /* already closed */ }
+        if (this.leaseWatchIntent !== intent || epoch !== this.presenceEpoch) {
+            this.retireDeliveryLeaseWatch(iter);
             return;
         }
         this.leaseWatchIter = iter;
@@ -6311,7 +6362,7 @@ export class CotalEndpoint extends EventEmitter {
         }
         if (!isUsablePresence(p)) {
             this.presenceBindingDrops++;
-            this.emitRecoverable(new Error(`dropped presence entry for key ${JSON.stringify(e.key)}: not a record with a string card.name, a known status and a finite ts`));
+            this.emitRecoverable(new Error(`dropped presence entry for key ${JSON.stringify(e.key)}: not a record with a string card.name, a known status, a finite ts, string display fields and a condition with a string code`));
             return;
         }
         this.applyPresence(e.key, p);
@@ -6738,12 +6789,22 @@ const PRESENCE_STATUSES = { idle: true, waiting: true, working: true, offline: t
  *  such as `"nope"` makes the liveness arithmetic NaN, and a JSON `1e400` parses as `Infinity`;
  *  neither age is ever greater than the TTL, so the row would stay live after its key expired
  *  (#2612). `card.name` is the roster sort key: a non-string throws inside the watch loop and
- *  ends the watch. `status` decides offline and is what roster consumers read. `card.id` is left
- *  to the KV-key check, which rejects anything but the key string. */
+ *  ends the watch. `status` decides offline and is what roster consumers read. `card.role`,
+ *  `activity`, `attention` and `condition.code` are printed as text, and the peer writes its own
+ *  row: an object such as `{"toString":null,"valueOf":null}` throws on conversion and would fail
+ *  every reader's roster. A present `condition` must be an object with a string `code`, which SPEC
+ *  §6 makes required: `null`, a bare string or an object with no code is dropped too. `card.id` is
+ *  left to the KV-key check, which rejects anything but the key string. */
 function isUsablePresence(value) {
     return isRecord(value) && isRecord(value.card) && typeof value.card.name === "string" &&
+        isOptionalString(value.card.role) &&
         typeof value.status === "string" && Object.hasOwn(PRESENCE_STATUSES, value.status) &&
-        typeof value.ts === "number" && Number.isFinite(value.ts);
+        typeof value.ts === "number" && Number.isFinite(value.ts) &&
+        isOptionalString(value.activity) && isOptionalString(value.attention) &&
+        (value.condition === undefined || (isRecord(value.condition) && typeof value.condition.code === "string"));
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === "string";
 }
 /** Shallow-equal two per-channel-mode maps (presence dedup): a change must re-emit, so an attention
  *  toggle isn't swallowed as a quiet heartbeat. Absent and empty compare equal. */
@@ -6837,19 +6898,6 @@ function describeStatusError(err) {
     }
     return err;
 }
-/** True when a failure is a NATS *permission denial* — the subject is forbidden to this
- *  endpoint's creds — rather than a missing responder or a timeout. The two need opposite
- *  fixes (grant the capability vs. start/await the service), so callers (e.g. a control
- *  request that can't reach the manager) must tell them apart instead of defaulting to
- *  "service down". Unwraps a wrapped `cause` and falls back to the server's error text, since
- *  a denied publish can surface either as the typed error or inside a request rejection. */
-export function isPermissionDenied(e) {
-    if (e instanceof PermissionViolationError)
-        return true;
-    if (e?.cause instanceof PermissionViolationError)
-        return true;
-    return /permissions?\s+violation/i.test(String(e?.message ?? ""));
-}
 /** The ordered consumer behind a KV watch, which nats.js keeps on the iterator and the KV types hide. */
 function kvWatchConsumer(iter) {
     const consumer = iter._data;