ocuclaw 1.3.3 → 1.3.4

package/dist/domain/debug-bundle-redaction.js

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+
+const DEFAULT_SAFE_KEYS = new Set([
+  "page", "pageCount", "selectedIndex", "cursor", "index", "count", "lane",
+  "slotState", "ms", "durationMs", "seq", "ok", "enabled", "connected",
+  "battery", "batteryLevel", "from", "to", "lines", "width", "height", "kind",
+  "severity", "state", "phase",
+]);
+
+const SAFE_KEYS = {
+  "sdk.frames": new Set([
+    "writeSeq", "chars", "lineCount", "selectedLane", "selectedCanonicalIndex",
+    "virtualPageCount", "slotIntent", "slotRunId", "indicator", "bodyHash",
+    "statusEmojiDecisionBranch", "streamingEmojiVariant", "startsWithNewline",
+    "endsWithNewline", "unifiedHeaderChars", "unifiedBodyChars",
+    "unifiedLeftTruncated", "payloadLiteMode", "containerName", "containerID",
+    "owner", "coalesced", "contentOffset", "contentLength",
+    "bridgeCallPrevented",
+  ]),
+
+  "glasses.lifecycle": new Set([
+    "surfaceId", "mode", "depth", "kind", "itemsMore",
+  ]),
+
+  "openclaw.message": new Set([
+    "runId",
+  ]),
+
+  "evenai": new Set([
+    "requestId", "bodyBytes", "messageChars", "model", "extraSystemPromptChars",
+    "routingMode", "sessionChanged", "listenEnabled", "dedupWindowMs",
+    "activeRequestId", "code", "elapsedMs", "timeoutMs", "textChars",
+  ]),
+
+  "voice.timeline": new Set([
+    "voiceSessionId", "trigger", "wasWaiting", "flagSource", "transcriptChars",
+    "sdkPackage",
+  ]),
+
+  "voice.transport": new Set([
+    "voiceSessionId", "trigger", "state", "transportMode",
+  ]),
+
+  "screen.nav": new Set([
+    "activeScreen", "navigationSeq", "inFlightNavigationSeq", "owner", "navSeq",
+    "source", "sysType", "textType", "listType", "menuDepth", "pendingCount",
+    "deferredDoubleClick", "coalesced", "replacedMenuActivation",
+  ]),
+
+  "render.ownership": new Set([
+    "activeScreen", "navigationSeq", "inFlightNavigationSeq", "owner",
+  ]),
+
+  "render.header_animation": new Set([
+    "slotRunId", "slotActivityId", "slotSeq", "slotCategory", "slotOrigin",
+    "slotPhase", "slotIntent", "expectedScreenLifecycleEpoch",
+  ]),
+
+  "render.virtual_pager.diagnostics": new Set([
+    "selectedLane", "selectedCanonicalIndex", "streamPageCount",
+    "historyPageCount", "autoFollow", "streamManualBrowseActive",
+    "handoffAnchorOffset",
+  ]),
+
+  "relay.protocol": new Set([
+    "messageId", "textChars", "hasAttachment", "attachmentBytes",
+    "upstreamDispatchMs", "localPublishMs", "onSendSyncMs", "clientId",
+    "persisted",
+  ]),
+
+  "relay.worker.health": new Set([
+    "workerEpoch", "mainFrameAgeMs", "mainHeartbeatAgeMs",
+    "workerMainQueueDepth", "workerQueueDepthByClass",
+  ]),
+
+  "relay.operation": new Set([
+    "requestId", "operation", "class", "clientId", "duplicate", "retainedFinal",
+  ]),
+
+  "relay.health": new Set([
+    "bufferedAmountBytes", "thresholdBytes", "clientId",
+  ]),
+  "relay.session": new Set([
+    "sessionId", "clientId",
+  ]),
+  "openclaw.run": new Set([
+    "role", "contentBlocks", "textChars", "rawAssistantChars",
+    "assistantDeltaChars", "firstGatewayChunk", "gatewayReceivedAtMs",
+    "gatewayToRelayIngressMs",
+  ]),
+
+  "app.lifecycle": new Set([
+    "requestId", "sinceMs", "flushed", "dropped",
+  ]),
+};
+
+const SECRET_KEY_RE = /token|secret|auth|apikey|api_key|password|cookie|bearer/i;
+const TOKEN_VALUE_RE = /[?&](?:token|access_token|key)=[^&\s"]+/gi;
+
+const SECRET_VALUE_RE = /(?:bearer\s+\S+|authorization\s*[:=]\s*(?:bearer\s+)?\S+|(?:access[_-]?token|token|secret|api[_-]?key|password|passwd|pwd)\s*=\s*\S+)/gi;
+
+const URL_AUTHORITY_RE = /\b(wss?|https?):\/\/[^\/\s"'?#]+/gi;
+
+const ADDRESS_KEY_RE = /^(?:url|uri|addr|address|host|hostname|endpoint|relay|gateway)(?:[A-Z_]|$)|(?:Url|Uri|Addr|Address|Host|Hostname|Endpoint|Relay|Gateway)(?:[A-Z_]|$)/;
+
+export function structuralPlaceholder(s) {
+
+  return s.replace(/\S/g, "■");
+}
+
+function safeKeysFor(cat) {
+  const extra = SAFE_KEYS[cat];
+  if (!extra) return DEFAULT_SAFE_KEYS;
+  return new Set([...DEFAULT_SAFE_KEYS, ...extra]);
+}
+
+function redactData(cat, data, mode) {
+  if (data == null || typeof data !== "object") return data;
+  const safe = safeKeysFor(cat);
+  const out = Array.isArray(data) ? [] : {};
+  for (const [k, v] of Object.entries(data)) {
+
+    if (SECRET_KEY_RE.test(k)) continue;
+    if (typeof v === "string") {
+
+      if (ADDRESS_KEY_RE.test(k)) {
+        out[k] = "[redacted-address]";
+        continue;
+      }
+
+      const cleaned = v
+        .replace(TOKEN_VALUE_RE, "[redacted]")
+        .replace(SECRET_VALUE_RE, "[redacted-secret]")
+        .replace(URL_AUTHORITY_RE, "$1://[redacted-host]");
+      if (safe.has(k) || mode === "off") {
+        out[k] = cleaned;
+      } else if (mode === "full") {
+        out[k] = "";
+      } else {
+        out[k] = structuralPlaceholder(cleaned);
+      }
+    } else if (v && typeof v === "object") {
+
+      out[k] = redactData(cat, v, mode);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function hashId(salt, value) {
+  return createHash("sha256").update(salt + ":" + value).digest("hex").slice(0, 16);
+}
+
+export function redactEvents(events, opts) {
+  const mode = opts && opts.mode ? opts.mode : "structural";
+  const idSalt = opts && typeof opts.idSalt === "string" ? opts.idSalt : "";
+  return events.map((evt) => {
+    const out = {
+      ts: evt.ts,
+      cat: evt.cat,
+      event: evt.event,
+      severity: evt.severity,
+      seq: evt.seq,
+      data: redactData(evt.cat, evt.data, mode),
+    };
+    if (typeof evt.sessionKey === "string" && evt.sessionKey) {
+      out.sessionKey = hashId(idSalt, evt.sessionKey);
+    }
+    if (typeof evt.runId === "string" && evt.runId) {
+      out.runId = hashId(idSalt, evt.runId);
+    }
+    if (typeof evt.screen === "string" && evt.screen) {
+
+      out.screen = evt.screen;
+    }
+    return out;
+  });
+}
+
+export { SAFE_KEYS, DEFAULT_SAFE_KEYS };

package/dist/domain/debug-bundle-save.js

@@ -0,0 +1,11 @@
+export function saveBundleToDisk(opts) {
+  const { saveDir, bundleId, savedMs, zip, metadataJson, fs, path } = opts;
+  const safeId = String(bundleId).replace(/[^A-Za-z0-9-]/g, "");
+  const stamp = new Date(savedMs).toISOString().slice(0, 19).replace(/[-:]/g, "") + "Z";
+  const base = stamp + "-" + safeId;
+  fs.mkdirSync(saveDir, { recursive: true });
+  const zipPath = path.join(saveDir, base + ".zip");
+  fs.writeFileSync(zipPath, zip);
+  fs.writeFileSync(path.join(saveDir, base + ".metadata.json"), metadataJson);
+  return { savedPath: zipPath, fileSize: zip.length };
+}

package/dist/domain/debug-bundle-zip.js

@@ -0,0 +1,15 @@
+import { zipSync, strToU8 } from "fflate";
+import { createHash } from "node:crypto";
+
+export function zipFiles(files) {
+  const entries = {};
+  for (const [name, content] of files) {
+    entries[name] = typeof content === "string" ? strToU8(content) : content;
+  }
+
+  return zipSync(entries, { mtime: new Date("1980-01-01") });
+}
+
+export function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}

package/dist/domain/debug-bundle.js

@@ -0,0 +1,97 @@
+import { bucketEventsToFiles, renderBundleReadme } from "./debug-bundle-format.js";
+import { redactEvents } from "./debug-bundle-redaction.js";
+import { zipFiles, sha256Hex } from "./debug-bundle-zip.js";
+import { strToU8 } from "fflate";
+
+const LIVEUI_LANE = ["glasses.lifecycle", "openclaw.message", "evenai"];
+const SCHEMA_VERSION = 1;
+const FORMAT_VERSION = 1;
+
+export function assembleBundle(dumpResult, opts) {
+  const appliedQuery = dumpResult.appliedQuery || {
+    categories: dumpResult.categories,
+    sinceMs: dumpResult.sinceMs,
+    untilMs: dumpResult.untilMs,
+  };
+
+  let events = redactEvents(dumpResult.events, { mode: opts.redactionMode, idSalt: opts.idSalt });
+  let ringCapped = opts.ringCappedWindow;
+
+  const dropOldest = () => {
+    events.sort((a, b) => a.ts - b.ts || (a.seq || 0) - (b.seq || 0));
+    events = events.slice(Math.ceil(events.length * 0.1));
+    ringCapped = true;
+  };
+
+  let built = buildArtifacts(events, dumpResult, appliedQuery, opts, ringCapped);
+
+  if (typeof opts.maxZipBytes === "number" && opts.maxZipBytes > 0) {
+    while (built.zip.length > opts.maxZipBytes && events.length > 0) {
+      dropOldest();
+      built = buildArtifacts(events, dumpResult, appliedQuery, opts, ringCapped);
+    }
+  }
+
+  return { zip: built.zip, bundleSha256: built.bundleSha256, metadata: built.metadata, chunks: built.chunks, files: built.files };
+}
+
+function buildArtifacts(events, dumpResult, appliedQuery, opts, ringCapped) {
+
+  const { files, summary } = bucketEventsToFiles({ events, ringEvents: dumpResult.ringEvents, ringCapacity: dumpResult.ringCapacity, appliedQuery });
+
+  const lane = events
+    .filter((e) => LIVEUI_LANE.includes(e.cat))
+    .sort((a, b) => a.ts - b.ts || (a.seq || 0) - (b.seq || 0));
+  if (lane.length) {
+    files.set("correlation-liveui.jsonl", lane.map((e) => JSON.stringify(e) + "\n").join(""));
+  }
+
+  files.set("README.md", renderBundleReadme(summary));
+
+  const contentNames = [...files.keys()].filter((n) => n !== "metadata.json").sort();
+  const concat = contentNames.map((n) => files.get(n)).join("");
+  const contentSha256 = sha256Hex(strToU8(concat));
+
+  const metadata = {
+    schemaVersion: SCHEMA_VERSION,
+    formatVersion: FORMAT_VERSION,
+    kind: "ocuclaw-debug-bundle",
+    capturedAtMs: dumpResult.nowMs,
+    window: {
+      fromMs: summary.timeRange ? summary.timeRange.fromMs : null,
+      toMs: summary.timeRange ? summary.timeRange.toMs : null,
+      spanMs: summary.timeRange ? summary.timeRange.spanMs : null,
+      ringCappedWindow: ringCapped,
+    },
+    ring: { events: dumpResult.ringEvents, capacity: dumpResult.ringCapacity },
+    totalBytes: summary.totalBytes,
+    contentSha256,
+    build: opts.build,
+    installId: opts.installId,
+    redactionMode: opts.redactionMode,
+    secretsStripped: true,
+    categories: summary.categories,
+    appliedQuery,
+    timeRange: summary.timeRange,
+    notes: { byteCountsArePostRedaction: true, appliedQueryIsPreExpansion: true, crossCategoryMergeKey: ["ts", "seq"] },
+    ticket: { id: null, reporter: null, note: opts.note || null, deviceModel: "G2" },
+  };
+  files.set("metadata.json", JSON.stringify(metadata, null, 2) + "\n");
+
+  const zip = zipFiles(files);
+  const bundleSha256 = sha256Hex(zip);
+  const chunks = chunkZip(zip, opts.chunkBytes);
+
+  return { files, summary, metadata, zip, bundleSha256, chunks };
+}
+
+export function chunkZip(zip, chunkBytes) {
+  const safeChunkBytes = Math.max(1, chunkBytes | 0);
+  const partCount = Math.max(1, Math.ceil(zip.length / safeChunkBytes));
+  const chunks = [];
+  for (let i = 0; i < partCount; i++) {
+    const slice = zip.subarray(i * safeChunkBytes, (i + 1) * safeChunkBytes);
+    chunks.push({ partIndex: i, partCount, partBase64: Buffer.from(slice).toString("base64") });
+  }
+  return chunks;
+}

package/dist/domain/debug-store.js

@@ -82,12 +82,7 @@ const DEFAULT_NOISY_CATEGORY_POLICIES = Object.freeze({
     ]),
   }),
   "sdk.frames": Object.freeze({
-    // sampleEvery: 1 disables the 1-in-N sampler. Every sdk.frames emit from
-    // MessageScreenWritePipeline is a sparse pipeline-invariant marker (flush,
-    // pipeline_exit, dedup_skipped, etc.) — none are high-rate enough to need
-    // sampling, and dropping them breaks flush↔exit pairing analyses that
-    // depend on seeing every iteration. dedupeWindowMs stays as a narrow
-    // safety net for adjacent same-name/same-prefix bursts.
+
     sampleEvery: 1,
     dedupeWindowMs: 150,
     alwaysAllow: Object.freeze([
@@ -154,16 +149,9 @@ function createDebugStore(opts) {
     ...DEFAULT_NOISY_CATEGORY_POLICIES,
     ...(options.noisyPolicies || {}),
   };
-  /** @type {Map<string, number>} */
+
   const enabledUntil = new Map();
 
-  // Rehydrate the arm from a persisted snapshot. relay-core reads debug-arm.json
-  // at construction and passes it here as options.initialEnabled, whose entries are
-  // the exact shape getSnapshot().enabled emits. That snapshot is already pruned of
-  // expired categories (getEnabledCategories -> pruneExpired), so the `> seedNow`
-  // re-check below is defensive belt-and-suspenders. Expired/unknown categories are
-  // SILENTLY skipped (do not log or warn on skip). Restoring the ORIGINAL absolute
-  // expiresAtMs makes a relay restart transparent without refreshing the TTL window.
   if (Array.isArray(options.initialEnabled)) {
     const seedNow = nowFn();
     for (const entry of options.initialEnabled) {
@@ -175,13 +163,10 @@ function createDebugStore(opts) {
     }
   }
 
-  /** @type {Map<string, number>} */
   const noisyCounters = new Map();
 
-  /** @type {Map<string, { key: string, ts: number }>} */
   const noisyLast = new Map();
 
-  /** @type {Array<object>} */
   const ring = new Array(capacity);
   let ringWrite = 0;
   let ringSize = 0;
@@ -509,9 +494,12 @@ function createDebugStore(opts) {
     const categorySet =
       categoriesFilter.length > 0 ? new Set(categoriesFilter) : null;
     const filtered = [];
+
+    let oldestMatchedMs = null;
     const all = getAllEvents();
     for (const evt of all) {
       if (categorySet && !categorySet.has(evt.cat)) continue;
+      if (oldestMatchedMs === null || evt.ts < oldestMatchedMs) oldestMatchedMs = evt.ts;
       if (sinceMs !== null && evt.ts < sinceMs) continue;
       if (untilMs !== null && evt.ts > untilMs) continue;
       filtered.push(evt);
@@ -537,6 +525,7 @@ function createDebugStore(opts) {
       events: formattedEvents,
       ringEvents: ringSize,
       ringCapacity: capacity,
+      oldestMatchedMs,
     };
   }
 

package/dist/domain/debug-upload-preset.js

@@ -0,0 +1,27 @@
+export const UPLOAD_CAPTURE_PRESET = [
+  "sdk.frames", "render.header_animation", "render.virtual_pager.diagnostics", "render.ownership",
+  "screen.nav", "app.lifecycle", "voice.timeline", "voice.transport",
+  "relay.session", "relay.protocol", "relay.health", "relay.worker.health", "relay.operation", "relay.transport",
+  "glasses.lifecycle", "openclaw.run", "openclaw.message", "evenai",
+];
+
+export function startUploadCaptureArming(deps) {
+  if (!deps.gatesOn()) return () => {};
+
+  const preset =
+    deps.preset && Array.isArray(deps.preset) && deps.preset.length ? deps.preset : UPLOAD_CAPTURE_PRESET;
+
+  const armSafely = () => {
+    try {
+      deps.armCategories(preset, deps.maxTtlMs);
+    } catch (err) {
+      if (deps.onArmError) deps.onArmError(err);
+    }
+  };
+  armSafely();
+  const handle = deps.setInterval(() => {
+    if (deps.gatesOn()) armSafely();
+  }, Math.round(0.8 * deps.maxTtlMs));
+  handle.unref();
+  return () => deps.clearInterval(handle);
+}

package/dist/domain/glasses-display-system-prompt.js

@@ -31,11 +31,6 @@ const SHARED_RULES =
 const ALLOWLIST_BLOCK =
   "Allowed emoji (copy exactly one per span):\n" + ALLOWLIST_LINES;
 
-/**
- * Compose the Channel-1 consolidated display-tags block.
- * @param {{emoji: boolean, pace: boolean}} opts - features ENABLED AT SESSION START
- * @returns {string} the block, or "" when neither feature is enabled
- */
 export function composeGlassesDisplaySystemPrompt(opts) {
   const emoji = !!(opts && opts.emoji);
   const pace = !!(opts && opts.pace);

package/dist/domain/glasses-display-system-prompt.test.js

@@ -25,7 +25,7 @@ test("pace-only includes dwell/skim, omits emoji + allowlist", () => {
   assert.match(out, /<dwell>/);
   assert.match(out, /<skim>/);
   assert.doesNotMatch(out, /<emoji:X>/);
-  // allowlist must not leak when emoji is off
+
   assert.ok(!out.includes(MESSAGE_EMOJI_ALLOWLIST[0]));
 });
 

package/dist/domain/glasses-ui-content-summary.js

@@ -10,11 +10,6 @@ function truncate(value, max) {
   return value.slice(0, Math.max(0, max - 1)) + "…";
 }
 
-/**
- * Summarize a glasses-UI render spec OR surface-update patch into a
- * token-bounded, structured shape: { kind, title?, items?, itemsMore?, body? }.
- * Pure; never throws.
- */
 function summarizeGlassesUiContent(specOrPatch) {
   const o = specOrPatch && typeof specOrPatch === "object" ? specOrPatch : {};
   const rawItems = Array.isArray(o.items) ? o.items : null;
@@ -46,7 +41,6 @@ function summarizeGlassesUiContent(specOrPatch) {
 
   if (typeof o.body === "string") out.body = truncate(o.body, BODY_MAX);
 
-  // Defensive cap: drop trailing items until under SUMMARY_MAX.
   while (
     Array.isArray(out.items) &&
     out.items.length > 1 &&

package/dist/domain/glasses-ui-system-prompt.test.js

@@ -6,8 +6,7 @@ test("pointer is short and references the tool + 'see its description'", () => {
   const out = composeGlassesUiNudgeSystemPrompt();
   assert.match(out, /render_glasses_ui/);
   assert.match(out, /description/i);
-  // ef8a821e carry: the deferred-tool search hint rides in the pointer so
-  // Codex-harness runs (tool not in the initial list) still find the tool.
+
   assert.match(out, /available\/deferred tools/);
   assert.ok(out.length < 420, `pointer should stay lean, got ${out.length}`);
 });

package/dist/domain/message-emoji-allowlist.js

@@ -1,10 +1,3 @@
-// Single source of truth for the 50-emoji allowlist used by the
-// message body-text filter, the Neural Emoji Reactor stream parser,
-// and the Neural Emoji Reactor system-prompt composer.
-//
-// Adding/removing entries here is a wire-protocol change in spirit:
-// the agent's prompt enumerates this list verbatim and the parser
-// rejects any tag with an off-list emoji.
 export const MESSAGE_EMOJI_ALLOWLIST = [
   "😂", "❤️", "🤣", "👍", "😭", "🙏", "😘", "🥰", "😍", "😊",
   "🎉", "😁", "💕", "🥺", "😅", "🔥", "☺️", "🤦", "🤷", "🙄",

package/dist/domain/message-emoji-filter.js

@@ -6,9 +6,7 @@ import {
 const EMOJI_CLUSTER_SEGMENTER = new Intl.Segmenter(undefined, {
   granularity: "grapheme",
 });
-// All emoji codepoints live above U+007F, so pure-ASCII text cannot contain
-// any emoji and the segmenter walk is pure overhead. This regex is the
-// gatekeeper for the fast path below.
+
 const NON_ASCII_RE = /[^\x00-\x7F]/;
 const RGI_EMOJI_SEQUENCE_RE = createOptionalRegex("^\\p{RGI_Emoji}$", "v");
 const EMOJI_CLUSTER_FALLBACK_RE =
@@ -103,10 +101,7 @@ function emitGapForTextEnd(mode, beforeRemoved, afterRemoved, removedEmojiInGap)
 }
 
 function filterAsciiDisplayFast(text) {
-  // Mirrors the segmenter walk for pure-ASCII display mode:
-  //   - whitespace immediately before a newline is dropped
-  //   - other [ \t]+ runs collapse to a single space
-  //   - trailing horizontal whitespace at end-of-text is stripped
+
   return text
     .replace(/[ \t]+(\r\n|\r|\n)/g, "$1")
     .replace(/[ \t]+/g, " ")
@@ -114,8 +109,7 @@ function filterAsciiDisplayFast(text) {
 }
 
 function filterAsciiRawFast(text) {
-  // Raw mode preserves inline whitespace; only the post-loop trailing-trim
-  // remains for pure-ASCII input.
+
   return text.replace(/[ \t]+$/g, "");
 }
 

package/dist/domain/neural-emoji-reactor-tag-config.js

@@ -35,18 +35,18 @@ export const EMOJI_TAG_FAMILY_CONFIG = {
 
   matchTrailingPartial(input, _suffixStart) {
     const n = input.length;
-    // 1) Trailing prefix of OPEN_PREFIX
+
     for (let len = Math.min(n, OPEN_PREFIX.length - 1); len > 0; len--) {
       const tail = input.slice(n - len);
       if (OPEN_PREFIX.startsWith(tail)) return len;
     }
-    // 2) Trailing OPEN_PREFIX + bytes not yet terminated by `>`
+
     const lastOpen = input.lastIndexOf(OPEN_PREFIX);
     if (lastOpen !== -1) {
       const after = input.indexOf(">", lastOpen + OPEN_PREFIX.length);
       if (after === -1) return n - lastOpen;
     }
-    // 3) Trailing prefix of CLOSE_TAG
+
     for (let len = Math.min(n, CLOSE_TAG.length - 1); len > 0; len--) {
       const tail = input.slice(n - len);
       if (CLOSE_TAG.startsWith(tail)) return len;

package/dist/domain/prompt-channel-fragments.js

@@ -7,22 +7,13 @@ const PACE_STOP =
 const RENDER_GATE =
   "No glasses display is connected right now; do not call render_glasses_ui.";
 
-/**
- * Compose the Channel-2 (before_prompt_build → appendSystemContext) fragment.
- * Returns undefined when nothing needs saying (the common case).
- *
- * @param {{startEnabled:{emoji:boolean,pace:boolean},
- *          currentEnabled:{emoji:boolean,pace:boolean},
- *          glassesConnected:boolean}} input
- * @returns {string|undefined}
- */
 export function composeChannelTwoFragment(input) {
   const start = (input && input.startEnabled) || { emoji: false, pace: false };
   const current = (input && input.currentEnabled) || { emoji: false, pace: false };
   const glassesConnected = !!(input && input.glassesConnected);
 
   const parts = [];
-  // Stop-notice only when a feature was ENABLED at start and is now OFF.
+
   if (start.emoji && !current.emoji) parts.push(EMOJI_STOP);
   if (start.pace && !current.pace) parts.push(PACE_STOP);
   if (!glassesConnected) parts.push(RENDER_GATE);

package/dist/domain/tagged-span-parser.js

@@ -1,30 +1,10 @@
 import { computeCodeSpanRegions } from "./code-span-regions.js";
 
-/**
- * @typedef {Object} TagFamilyConfig
- * @property {string} name
- * @property {ReadonlyArray<string>} closeLiterals
- * @property {(input: string, atOffset: number) => { consumed: number, spanInit: object } | null} matchOpen
- * @property {(input: string, atOffset: number) => { consumed: number, closeKind: any } | null} matchClose
- * @property {(activeOpen: object, closeKind: any) => boolean} closeMatches
- * @property {(input: string, suffixStart: number) => number} matchTrailingPartial
- * @property {(spanInit: object) => boolean} [validateOpen]
- * @property {(spanInit: object) => void} [onRejected]
- */
-
-/**
- * @param {string} accumulatedText
- * @param {ReadonlyArray<TagFamilyConfig>} families
- * @returns {{ cleanText: string, spansByFamily: Record<string, object[]>, trailingPartialTag: boolean }}
- */
 export function parseTaggedSpans(accumulatedText, families) {
   const spansByFamily = {};
   const activeOpens = new Map();
   for (const fam of families) spansByFamily[fam.name] = [];
 
-  // Compute holdback once: each family declares how many trailing bytes look
-  // like the start of one of its tags; max wins. Held-back bytes are kept
-  // out of the parse loop so they neither become spans nor leak verbatim.
   let holdback = 0;
   for (const fam of families) {
     const vote = fam.matchTrailingPartial(accumulatedText, 0);
@@ -32,8 +12,6 @@ export function parseTaggedSpans(accumulatedText, families) {
   }
   const scanEnd = accumulatedText.length - holdback;
 
-  // Tags quoted inside markdown code (inline backticks / fenced blocks) are
-  // literal text, not live tags — copy those regions through verbatim.
   const codeRegions = computeCodeSpanRegions(accumulatedText);
   let codeRegionIdx = 0;
 
@@ -58,7 +36,7 @@ export function parseTaggedSpans(accumulatedText, families) {
       continue;
     }
     if (accumulatedText[i] === "<") {
-      // Try each family's matchClose, then matchOpen, in registration order.
+
       for (const fam of families) {
         const close = fam.matchClose(accumulatedText, i);
         if (close) {
@@ -71,7 +49,7 @@ export function parseTaggedSpans(accumulatedText, families) {
             });
             activeOpens.delete(fam.name);
           }
-          // mismatched or dangling close → drop silently
+
           i += close.consumed;
           continue outer;
         }
@@ -79,7 +57,7 @@ export function parseTaggedSpans(accumulatedText, families) {
       for (const fam of families) {
         const open = fam.matchOpen(accumulatedText, i);
         if (open) {
-          // Latest-wins same-family: close any active span at current offset.
+
           const prior = activeOpens.get(fam.name);
           if (prior) {
             spansByFamily[fam.name].push({
@@ -104,7 +82,6 @@ export function parseTaggedSpans(accumulatedText, families) {
     i += 1;
   }
 
-  // Unclosed spans → run to cleanText end.
   for (const fam of families) {
     const active = activeOpens.get(fam.name);
     if (active) {

package/dist/domain/tagged-span-strip.js

@@ -1,8 +1,3 @@
-// Syntactic strip for all tagged-span grammar families.
-// Removes well-formed openers and closers; keeps wrapped content.
-// Removes orphan halves of either. Idempotent. No allowlist enforcement.
-// Tags quoted inside markdown code (inline backticks / fenced blocks) are
-// preserved verbatim so agents can talk about the tag grammar literally.
 import { computeCodeSpanRegions } from "./code-span-regions.js";
 
 const EMOJI_OPEN_RE = /<emoji:[^<>\s]+?>/g;
@@ -10,8 +5,6 @@ const EMOJI_CLOSE_RE = /<\/emoji>/g;
 const PACE_OPEN_RE = /<(?:dwell|skim)>/g;
 const PACE_CLOSE_RE = /<\/(?:dwell|skim)>/g;
 
-// Single alternation so one pass over the original string keeps match
-// offsets valid for the code-region exemption check.
 const ALL_TAGS_RE = new RegExp(
   [
     EMOJI_OPEN_RE.source,