letagents 0.12.33 → 0.12.35

package/shared/message-reactions.mjs

@@ -0,0 +1,130 @@
+// Emoji reactions on room messages: the limits, the quick palette and the one
+// validation rule that the server and both clients share.
+
+export const MESSAGE_REACTION_EMOJI_MAX_BYTES = 64;
+export const MESSAGE_REACTION_MAX_DISTINCT_PER_MESSAGE = 20;
+// A reaction always reports its exact count; only the named reactors are capped.
+export const MESSAGE_REACTION_MAX_REACTORS_LISTED = 50;
+// One range read covers at most this many message numbers, and returns at most
+// this many reactor rows before it stops and names where to continue.
+export const MESSAGE_REACTION_RANGE_MAX_SPAN = 1000;
+export const MESSAGE_REACTION_MAX_PER_READ = 2000;
+
+export const MESSAGE_REACTION_QUICK_EMOJI = Object.freeze([
+  "👍", "👎", "✅", "❌", "👀", "🙏", "🎉", "🚀",
+  "❤️", "😂", "🤔", "😅", "🔥", "💯", "👏", "🙌",
+  "🤝", "⚠️", "🐛", "🔧", "📌", "⏳", "💡", "❓",
+]);
+
+const VARIATION_SELECTOR_16 = "️";
+const encoder = new TextEncoder();
+
+// `\p{RGI_Emoji}` needs the `v` flag, which every runtime we ship has. The
+// fallback keeps an older browser usable; the server stays the authority.
+const emojiPattern = (() => {
+  try {
+    return new RegExp("^\\p{RGI_Emoji}$", "v");
+  } catch {
+    return /^(?:\p{Regional_Indicator}{2}|[#*0-9]️?⃣|\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?(?:‍\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?)*)$/u;
+  }
+})();
+
+/**
+ * Return the canonical form of one emoji, or null when the value is anything
+ * else (text, several emoji, an oversized sequence).
+ */
+export function normalizeMessageReactionEmoji(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed || encoder.encode(trimmed).length > MESSAGE_REACTION_EMOJI_MAX_BYTES) return null;
+  if (emojiPattern.test(trimmed)) return trimmed;
+  // A bare text-style symbol such as "❤" is the same reaction as "❤️".
+  const qualified = `${trimmed}${VARIATION_SELECTOR_16}`;
+  return emojiPattern.test(qualified) ? qualified : null;
+}
+
+function normalizeReactor(value) {
+  if (!value || typeof value !== "object") return null;
+  const login = typeof value.login === "string" ? value.login.trim() : "";
+  if (!login || login.length > 256) return null;
+  const name = typeof value.name === "string" && value.name.trim() ? value.name.trim().slice(0, 256) : login;
+  const avatarUrl = typeof value.avatar_url === "string" && /^https:\/\//.test(value.avatar_url)
+    ? value.avatar_url.slice(0, 2048)
+    : null;
+  return { login, name, avatar_url: avatarUrl };
+}
+
+/**
+ * Read a server reaction list defensively. Anything malformed is dropped, so a
+ * client never renders a reaction it could not also send.
+ */
+export function normalizeMessageReactions(value) {
+  if (!Array.isArray(value)) return [];
+  const reactions = [];
+  const seen = new Set();
+  for (const item of value) {
+    if (reactions.length >= MESSAGE_REACTION_MAX_DISTINCT_PER_MESSAGE) break;
+    if (!item || typeof item !== "object") continue;
+    const emoji = normalizeMessageReactionEmoji(item.emoji);
+    if (!emoji || seen.has(emoji)) continue;
+    const reactors = (Array.isArray(item.reactors) ? item.reactors : [])
+      .slice(0, MESSAGE_REACTION_MAX_REACTORS_LISTED)
+      .map(normalizeReactor)
+      .filter(Boolean);
+    const count = Number.isSafeInteger(item.count) && item.count > 0 ? item.count : reactors.length;
+    if (count <= 0) continue;
+    seen.add(emoji);
+    reactions.push({ emoji, count: Math.max(count, reactors.length), reactors });
+  }
+  return reactions;
+}
+
+function sameLogin(left, right) {
+  return typeof left === "string" && typeof right === "string"
+    && left.length > 0 && left.toLowerCase() === right.toLowerCase();
+}
+
+/** Whether the listed reactors include the viewer. */
+export function viewerReactedWith(reaction, viewerLogin) {
+  return Boolean(reaction?.reactors?.some((reactor) => sameLogin(reactor.login, viewerLogin)));
+}
+
+/** "You, Ada and 3 others reacted with 👍" — the tooltip and the accessible name. */
+export function describeMessageReaction(reaction, viewerLogin) {
+  const reactors = Array.isArray(reaction?.reactors) ? reaction.reactors : [];
+  const viewerReacted = viewerReactedWith(reaction, viewerLogin);
+  const names = [
+    ...(viewerReacted ? ["You"] : []),
+    ...reactors.filter((reactor) => !sameLogin(reactor.login, viewerLogin)).map((reactor) => reactor.name),
+  ];
+  const count = Math.max(Number(reaction?.count) || 0, names.length);
+  const shown = names.slice(0, 3);
+  const others = count - shown.length;
+  if (others > 0) shown.push(others === 1 ? "1 other" : `${others} others`);
+  const who = shown.length <= 1
+    ? shown[0] ?? "Someone"
+    : `${shown.slice(0, -1).join(", ")} and ${shown.at(-1)}`;
+  return `${who} reacted with ${reaction?.emoji ?? ""}`.trim();
+}
+
+/**
+ * The reaction list after the viewer toggles one emoji, for an optimistic
+ * update. The server's answer replaces it either way.
+ */
+export function toggleViewerMessageReaction(reactions, emoji, viewer) {
+  const current = Array.isArray(reactions) ? reactions : [];
+  const existing = current.find((reaction) => reaction.emoji === emoji);
+  if (!existing) {
+    return [...current, { emoji, count: 1, reactors: [{ ...viewer }] }];
+  }
+  if (viewerReactedWith(existing, viewer.login)) {
+    const reactors = existing.reactors.filter((reactor) => !sameLogin(reactor.login, viewer.login));
+    const count = existing.count - 1;
+    return count <= 0
+      ? current.filter((reaction) => reaction !== existing)
+      : current.map((reaction) => (reaction === existing ? { ...existing, count, reactors } : reaction));
+  }
+  return current.map((reaction) => (reaction === existing
+    ? { ...existing, count: existing.count + 1, reactors: [...existing.reactors, { ...viewer }] }
+    : reaction));
+}

package/shared/message-search-controller.d.mts

@@ -0,0 +1,38 @@
+import type { MessageSearchQueryError, MessageSearchResponse } from "./message-search.mjs";
+
+export const MESSAGE_SEARCH_DEBOUNCE_MS: 250;
+
+export interface MessageSearchState<Hit extends { id: string }> {
+  /**
+   * `idle`: nothing to search yet. `invalid`: the query breaks a limit (see `error`).
+   * `loading`: the first page is on its way. `ready` / `error`: it arrived, or failed.
+   */
+  status: "idle" | "invalid" | "loading" | "ready" | "error";
+  terms: readonly string[];
+  /** Newest first. */
+  hits: readonly Hit[];
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** A query limit name when `invalid`; otherwise the last request's failure, if any. */
+  error: MessageSearchQueryError | string | null;
+}
+
+export interface MessageSearchController<Hit extends { id: string }> {
+  readonly state: MessageSearchState<Hit>;
+  /** Search for a new query after a short pause in typing. */
+  setQuery(value: string): void;
+  /** Read the next, older page of the current results. */
+  loadMore(): Promise<void>;
+  /** Stop searching; call when the search closes or the room changes. */
+  reset(): void;
+}
+
+/**
+ * The client-side state of one room's history search, shared by the desktop
+ * and web apps. Answers that arrive for an earlier query are dropped.
+ */
+export function createMessageSearchController<Hit extends { id: string }>(options: {
+  search(query: string, before: string | null): Promise<Pick<MessageSearchResponse<Hit>, "messages" | "has_more" | "next_before"> & { terms?: string[] }>;
+  onChange?(): void;
+  debounceMs?: number;
+}): MessageSearchController<Hit>;

package/shared/message-search-controller.mjs

@@ -0,0 +1,99 @@
+// The client-side state of one room's history search, shared by the desktop
+// and web apps. Framework-free: the app supplies the request and is told when
+// something changed.
+import { parseMessageSearchQuery } from "./message-search.mjs";
+
+export const MESSAGE_SEARCH_DEBOUNCE_MS = 250;
+
+const IDLE = Object.freeze({ status: "idle", terms: [], hits: [], hasMore: false, loadingMore: false, error: null });
+
+export function createMessageSearchController({ search, onChange, debounceMs = MESSAGE_SEARCH_DEBOUNCE_MS }) {
+  let state = IDLE;
+  let query = "";
+  let nextBefore = null;
+  // Every new query (and reset) starts an epoch; answers from an earlier one are dropped.
+  let epoch = 0;
+  let timer = null;
+
+  function set(next) {
+    state = next;
+    onChange?.();
+  }
+
+  function cancelTimer() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  }
+
+  async function run(terms, startedIn) {
+    try {
+      const page = await search(query, null);
+      if (startedIn !== epoch) return;
+      nextBefore = page?.next_before ?? null;
+      set({
+        status: "ready",
+        terms: Array.isArray(page?.terms) ? page.terms : terms,
+        hits: Array.isArray(page?.messages) ? page.messages : [],
+        hasMore: Boolean(page?.has_more && nextBefore),
+        loadingMore: false,
+        error: null,
+      });
+    } catch (error) {
+      if (startedIn !== epoch) return;
+      set({ ...IDLE, status: "error", terms, error: error instanceof Error && error.message ? error.message : "Search failed." });
+    }
+  }
+
+  /** Search for a new query after a short pause in typing. */
+  function setQuery(value) {
+    const next = typeof value === "string" ? value : "";
+    if (next.trim() === query.trim() && state !== IDLE) return;
+    query = next;
+    epoch += 1;
+    cancelTimer();
+    nextBefore = null;
+    const parsed = parseMessageSearchQuery(query);
+    if (parsed.error) {
+      // Too short is simply "not searching yet"; the other limits are worth saying.
+      set(parsed.error === "too_short" ? IDLE : { ...IDLE, status: "invalid", error: parsed.error });
+      return;
+    }
+    const startedIn = epoch;
+    set({ ...IDLE, status: "loading", terms: parsed.terms });
+    timer = setTimeout(() => {
+      timer = null;
+      void run(parsed.terms, startedIn);
+    }, debounceMs);
+  }
+
+  /** Read the next, older page of the current results. */
+  async function loadMore() {
+    if (state.status !== "ready" || !state.hasMore || state.loadingMore || !nextBefore) return;
+    const startedIn = epoch;
+    const before = nextBefore;
+    set({ ...state, loadingMore: true, error: null });
+    try {
+      const page = await search(query, before);
+      if (startedIn !== epoch) return;
+      nextBefore = page?.next_before ?? null;
+      const known = new Set(state.hits.map((hit) => hit.id));
+      const more = (Array.isArray(page?.messages) ? page.messages : []).filter((hit) => !known.has(hit.id));
+      set({ ...state, hits: [...state.hits, ...more], hasMore: Boolean(page?.has_more && nextBefore), loadingMore: false });
+    } catch (error) {
+      if (startedIn !== epoch) return;
+      // Keep what is shown; the person can press "more" again.
+      set({ ...state, loadingMore: false, error: error instanceof Error && error.message ? error.message : "Search failed." });
+    }
+  }
+
+  /** Stop searching; call when the search closes or the room changes. */
+  function reset() {
+    query = "";
+    epoch += 1;
+    cancelTimer();
+    nextBefore = null;
+    if (state !== IDLE) set(IDLE);
+  }
+
+  return { get state() { return state; }, setQuery, loadMore, reset };
+}

package/shared/message-search.d.mts

@@ -0,0 +1,46 @@
+export const MESSAGE_SEARCH_MIN_QUERY_CHARS: 2;
+export const MESSAGE_SEARCH_MAX_QUERY_CHARS: 200;
+export const MESSAGE_SEARCH_MAX_TERMS: 6;
+export const MESSAGE_SEARCH_DEFAULT_LIMIT: 30;
+export const MESSAGE_SEARCH_MAX_LIMIT: 50;
+
+export type MessageSearchQueryError = "too_short" | "too_long" | "too_many_terms";
+
+export type ParsedMessageSearchQuery =
+  | { terms: string[]; error?: undefined }
+  | { error: MessageSearchQueryError; terms?: undefined };
+
+/**
+ * Split a query into its terms, or say why it cannot be searched. A term is a
+ * word, or a phrase in double quotes; a message matches when it contains every
+ * term as a substring, ignoring case.
+ */
+export function parseMessageSearchQuery(value: unknown): ParsedMessageSearchQuery;
+
+/** Whether a text contains every term, the same test the server applies. */
+export function textMatchesMessageSearch(text: unknown, terms: readonly string[]): boolean;
+
+/** `GET /rooms/:room/messages/search` */
+export interface MessageSearchResponse<Message = unknown> {
+  room_id: string;
+  terms: string[];
+  /** Newest first. */
+  messages: Message[];
+  has_more: boolean;
+  /** Pass as `before` to read the next, older page; null on the last page. */
+  next_before: string | null;
+}
+
+export interface MessageSearchSegment {
+  text: string;
+  match: boolean;
+}
+
+/**
+ * Split a text into runs that do and do not match the terms, for rendering
+ * highlights as plain text nodes (never as HTML).
+ */
+export function highlightMessageSearchText(text: unknown, terms: readonly string[]): MessageSearchSegment[];
+
+/** A short excerpt around the first match, with an ellipsis where text was left out. */
+export function messageSearchSnippet(text: unknown, terms: readonly string[], maxLength?: number): string;

package/shared/message-search.mjs

@@ -0,0 +1,114 @@
+// Searching a room's messages: the limits and the one query grammar that the
+// server and both apps share. A query is a list of terms; a message matches
+// when it contains every term, ignoring case. A term is a word, or a phrase
+// in double quotes. Matching is by substring, so part of an identifier, a
+// file path or an error string finds the message.
+
+export const MESSAGE_SEARCH_MIN_QUERY_CHARS = 2;
+export const MESSAGE_SEARCH_MAX_QUERY_CHARS = 200;
+export const MESSAGE_SEARCH_MAX_TERMS = 6;
+export const MESSAGE_SEARCH_DEFAULT_LIMIT = 30;
+export const MESSAGE_SEARCH_MAX_LIMIT = 50;
+
+/**
+ * Split a query into its terms, or say why it cannot be searched.
+ * Returns `{ terms }` or `{ error: "too_short" | "too_long" | "too_many_terms" }`.
+ */
+export function parseMessageSearchQuery(value) {
+  const query = typeof value === "string" ? value.trim() : "";
+  if (query.length > MESSAGE_SEARCH_MAX_QUERY_CHARS) return { error: "too_long" };
+
+  const terms = [];
+  const seen = new Set();
+  // A phrase runs to its closing quote, or to the end when the quote is never closed.
+  for (const match of query.matchAll(/"([^"]*)"?|(\S+)/g)) {
+    const term = (match[1] ?? match[2] ?? "").replace(/\s+/g, " ").trim();
+    const key = term.toLowerCase();
+    if (!term || seen.has(key)) continue;
+    seen.add(key);
+    terms.push(term);
+  }
+  if (terms.join("").length < MESSAGE_SEARCH_MIN_QUERY_CHARS) return { error: "too_short" };
+  if (terms.length > MESSAGE_SEARCH_MAX_TERMS) return { error: "too_many_terms" };
+  return { terms };
+}
+
+/** Whether a text contains every term, the same test the server applies. */
+export function textMatchesMessageSearch(text, terms) {
+  const haystack = String(text ?? "").toLowerCase();
+  return terms.length > 0 && terms.every((term) => haystack.includes(term.toLowerCase()));
+}
+
+function matchRanges(text, terms) {
+  const lower = text.toLowerCase();
+  // Lowercasing can expand a character (İ -> i + combining dot). Keep the
+  // original UTF-16 boundaries so highlights and snippets still slice source text.
+  let sourceOffsets = null;
+  if (lower.length !== text.length) {
+    sourceOffsets = [];
+    let start = 0;
+    for (const character of text) {
+      const end = start + character.length;
+      for (let index = 0; index < character.toLowerCase().length; index += 1) {
+        sourceOffsets.push([start, end]);
+      }
+      start = end;
+    }
+    // Context-sensitive casing must not leave offsets outside the map.
+    if (sourceOffsets.length !== lower.length) return [];
+  }
+  const ranges = [];
+  for (const term of terms) {
+    const needle = term.toLowerCase();
+    if (!needle) continue;
+    for (let at = lower.indexOf(needle); at !== -1; at = lower.indexOf(needle, at + 1)) {
+      ranges.push(sourceOffsets
+        ? [sourceOffsets[at][0], sourceOffsets[at + needle.length - 1][1]]
+        : [at, at + needle.length]);
+    }
+  }
+  ranges.sort((left, right) => left[0] - right[0] || left[1] - right[1]);
+  // Overlapping and touching matches read as one highlighted run.
+  const merged = [];
+  for (const range of ranges) {
+    const last = merged.at(-1);
+    if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]);
+    else merged.push([...range]);
+  }
+  return merged;
+}
+
+/**
+ * Split a text into runs that do and do not match the terms, for rendering
+ * highlights as plain text nodes (never as HTML).
+ */
+export function highlightMessageSearchText(text, terms) {
+  const source = String(text ?? "");
+  const segments = [];
+  let cursor = 0;
+  for (const [start, end] of matchRanges(source, terms)) {
+    if (start > cursor) segments.push({ text: source.slice(cursor, start), match: false });
+    segments.push({ text: source.slice(start, end), match: true });
+    cursor = end;
+  }
+  if (cursor < source.length) segments.push({ text: source.slice(cursor), match: false });
+  return segments;
+}
+
+/**
+ * A short excerpt around the first match: whitespace collapsed, cut at
+ * `maxLength` characters, with an ellipsis where text was left out.
+ */
+export function messageSearchSnippet(text, terms, maxLength = 220) {
+  const source = String(text ?? "").replace(/\s+/g, " ").trim();
+  if (source.length <= maxLength) return source;
+  const first = matchRanges(source, terms)[0]?.[0] ?? 0;
+  // Keep a little lead-in so the match is read in its sentence.
+  let start = Math.max(0, Math.min(first - Math.floor(maxLength / 4), source.length - maxLength));
+  if (start > 0) {
+    const space = source.indexOf(" ", start);
+    if (space !== -1 && space < first) start = space + 1;
+  }
+  const end = Math.min(source.length, start + maxLength);
+  return `${start > 0 ? "…" : ""}${source.slice(start, end).trim()}${end < source.length ? "…" : ""}`;
+}

package/shared/paced-queue.d.mts

@@ -0,0 +1,28 @@
+export class PacedQueueClosedError extends Error {
+  constructor(message?: string);
+}
+
+export type PacedQueueOptions = {
+  capacity: number;
+  /** Slots only rank-0 (urgent) work may use. */
+  reservedForUrgent?: number;
+  leaseMs: number;
+  startJitterMs?: number;
+  random?: () => number;
+  setTimeout?: typeof setTimeout;
+  clearTimeout?: typeof clearTimeout;
+};
+
+export type PacedQueueAdmission = {
+  rank?: () => number | Promise<number>;
+  pauseWhenQueued?: () => boolean;
+  signal?: AbortSignal;
+};
+
+export class PacedQueue {
+  constructor(options: PacedQueueOptions);
+  acquire(key: string, admission?: PacedQueueAdmission): Promise<() => void>;
+  reprioritize(key: string, rank: number): void;
+  close(createError?: () => Error): void;
+  snapshot(): { active: number; queued: string[] };
+}

package/shared/paced-queue.mjs

@@ -0,0 +1,159 @@
+/**
+ * A bounded, priority-ordered admission queue for work that loads a shared
+ * server or the machine. It exists so that "everything at once" (a desktop
+ * start or a daemon handoff converging every agent together) becomes a few
+ * at a time, most urgent first.
+ *
+ * Queue time is never part of the queued work: callers start their own
+ * request timeouts and startup budgets after a slot is granted. Callers must
+ * pace only leaf work that never waits for another slot of the same queue,
+ * so a queue cannot deadlock on itself.
+ */
+
+export class PacedQueueClosedError extends Error {
+  constructor(message = "Queued work was cancelled because its owner is shutting down.") {
+    super(message);
+    this.name = "PacedQueueClosedError";
+  }
+}
+
+export class PacedQueue {
+  #capacity;
+  #reservedForUrgent;
+  #leaseMs;
+  #startJitterMs;
+  #random;
+  #setTimeout;
+  #clearTimeout;
+  #active = 0;
+  #queue = [];
+  #sequence = 0;
+  #closedError = null;
+
+  /**
+   * Rank 0 is urgent work (a user's action). `reservedForUrgent` of the
+   * `capacity` slots serve only it, so a queue full of background work can
+   * never make a user wait for one of that work's slots to free up.
+   */
+  constructor({ capacity, reservedForUrgent = 0, leaseMs, startJitterMs = 0, random = Math.random, setTimeout: setTimer = setTimeout, clearTimeout: clearTimer = clearTimeout }) {
+    if (!Number.isSafeInteger(capacity) || capacity < 1) throw new Error("A paced queue needs a positive capacity.");
+    if (!Number.isSafeInteger(reservedForUrgent) || reservedForUrgent < 0 || reservedForUrgent >= capacity) {
+      throw new Error("A paced queue must leave background work at least one slot.");
+    }
+    if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new Error("A paced queue needs a positive slot lease.");
+    this.#capacity = capacity;
+    this.#reservedForUrgent = reservedForUrgent;
+    this.#leaseMs = leaseMs;
+    this.#startJitterMs = startJitterMs;
+    this.#random = random;
+    this.#setTimeout = setTimer;
+    this.#clearTimeout = clearTimer;
+  }
+
+  /**
+   * Wait for a slot and return its idempotent release. `rank` (lower runs
+   * first) is read only when the work has to queue. After a queued slot is
+   * granted, `pauseWhenQueued` decides whether to wait a random pause of up
+   * to the start jitter, so a released batch spreads out. Aborting `signal`
+   * while queued removes the work from the queue and rejects.
+   */
+  async acquire(key, { rank = () => 0, pauseWhenQueued = () => true, signal } = {}) {
+    if (this.#closedError) throw this.#closedError();
+    signal?.throwIfAborted();
+    // Room even for background work and nobody waiting: no rank needed.
+    if (this.#queue.length === 0 && this.#active < this.#capacity - this.#reservedForUrgent) {
+      this.#active += 1;
+      return this.#lease();
+    }
+    const resolvedRank = await rank();
+    if (this.#closedError) throw this.#closedError();
+    signal?.throwIfAborted();
+    let grant;
+    let cancel;
+    const admitted = new Promise((resolve, reject) => { grant = resolve; cancel = reject; });
+    const waiter = { key, rank: resolvedRank, sequence: this.#sequence++, granted: false, grant, cancel };
+    if (signal) {
+      const abandon = () => {
+        const index = this.#queue.indexOf(waiter);
+        if (index < 0) return;
+        this.#queue.splice(index, 1);
+        cancel(signal.reason);
+      };
+      signal.addEventListener("abort", abandon, { once: true });
+      waiter.grant = () => { signal.removeEventListener("abort", abandon); grant(); };
+      waiter.cancel = (error) => { signal.removeEventListener("abort", abandon); cancel(error); };
+    }
+    this.#queue.push(waiter);
+    this.#sort();
+    // A slot may have been released while the rank was read, or this may be
+    // urgent work entitled to a reserved slot.
+    this.#pump();
+    const waited = !waiter.granted;
+    await admitted;
+    const release = this.#lease();
+    if (waited && this.#startJitterMs > 0 && pauseWhenQueued()) {
+      const pauseMs = Math.floor(this.#random() * this.#startJitterMs);
+      if (pauseMs > 0) await new Promise((resolve) => { this.#setTimeout(resolve, pauseMs); });
+    }
+    return release;
+  }
+
+  /** Move already-queued work for `key` forward to `rank`; never moves it back. */
+  reprioritize(key, rank) {
+    let changed = false;
+    for (const waiter of this.#queue) {
+      if (waiter.key === key && waiter.rank > rank) {
+        waiter.rank = rank;
+        changed = true;
+      }
+    }
+    if (changed) {
+      this.#sort();
+      this.#pump();
+    }
+  }
+
+  /** Cancel queued work and refuse new work; work already admitted runs on. */
+  close(createError = () => new PacedQueueClosedError()) {
+    this.#closedError = createError;
+    for (const waiter of this.#queue.splice(0)) waiter.cancel(createError());
+  }
+
+  snapshot() {
+    return { active: this.#active, queued: this.#queue.map((waiter) => waiter.key) };
+  }
+
+  /** Admit queued work from the front while it has a slot it may use. */
+  #pump() {
+    while (this.#queue.length > 0) {
+      const head = this.#queue[0];
+      const limit = head.rank === 0 ? this.#capacity : this.#capacity - this.#reservedForUrgent;
+      // The queue is ordered by rank, so nothing behind a blocked head may run either.
+      if (this.#active >= limit) return;
+      this.#queue.shift();
+      this.#active += 1;
+      head.granted = true;
+      head.grant();
+    }
+  }
+
+  #sort() {
+    this.#queue.sort((left, right) => left.rank - right.rank || left.sequence - right.sequence);
+  }
+
+  #lease() {
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      this.#clearTimeout(timer);
+      this.#active -= 1;
+      this.#pump();
+    };
+    // Every queued operation keeps its own timeout; the lease only stops one
+    // that never settles from holding its slot forever.
+    const timer = this.#setTimeout(release, this.#leaseMs);
+    timer?.unref?.();
+    return release;
+  }
+}

package/shared/permission-review.d.mts

@@ -19,6 +19,25 @@ export type PermissionReviewRequest = {
 /** True when a person must decide: no fixed rule can read the command in full. */
 export function commandNeedsPerson(command: unknown, project: unknown): boolean;
 
+/** True when each simple command in each part is, word for word, one in the whole command. */
+export function partsAreInCommand(command: unknown, parts: unknown): boolean;
+
+/** True when every part only reads project files, history, or this repository's pull requests and issues. */
+export function commandOnlyReads(command: unknown, project: unknown): boolean;
+
+export type RoutineCommandContext = {
+  /** Whether a branch is the agent's own. */
+  ownBranch(branch: string): boolean;
+  /** The branch `origin` names as its default; null when it is not known. */
+  defaultBranch: string | null;
+};
+
+/**
+ * Null when a person must decide. Otherwise the parts Jev must still review,
+ * each as written: none when the rules alone allow the whole command.
+ */
+export function routineCommandReview(command: unknown, project: unknown, context: RoutineCommandContext): string[] | null;
+
 /** Null when the fixed rules already require a person. */
 export function buildPermissionReviewRequest(input: {
   commands: readonly string[];