Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(open-knowledge): bundle checkpoint refs, agent effects, drop counts (#2735)
Andrew Mikofalvya8072a2fbaeb
diff --git a/.changeset/bundle-checkpoint-effects-drop-counts.md b/.changeset/bundle-checkpoint-effects-drop-counts.mdnew file mode 100644index 000000000..cb9ee7930--- /dev/null+++ b/.changeset/bundle-checkpoint-effects-drop-counts.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Diagnostics bundles now capture more of what matters for content-loss triage. The full bundle stages the shadow repo's recovery-checkpoint refs (`state/checkpoint-refs.txt` — ref name, date, and content-free subject per checkpoint) and a new `state/agent-effects.json` snapshot of the per-document agent activity ring buffers, served by a new loopback-only `GET /api/metrics/agent-effects` endpoint that summarizes agent writes as character counts (never raw text). Doc names in the new artifacts are anonymized by the existing `--redact` pass, which now also hashes the agent-presence bundle's `currentDoc` path so a redacted `state/agent-presence.json` no longer leaks the document a person was editing. The web client's log forwarder also stops losing entries silently: drops from buffer overflow or failed uploads are counted and recorded as an explicit `droppedSinceLastFlush` gap marker in the server log on the next delivered batch, and a failed recovery-checkpoint write now also emits a structured server-log line with doc and branch context.diff --git a/knip.config.ts b/knip.config.tsindex 9633755a0..16d637b4b 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -119,9 +119,7 @@ export default {'packages/server': {entry: ['src/**/*.test.ts'],project: 'src/**',- ignoreDependencies: [- '@types/shell-quote',- ],+ ignoreDependencies: ['@types/shell-quote'],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts'],diff --git a/packages/app/src/lib/install-client-log-forwarder.test.ts b/packages/app/src/lib/install-client-log-forwarder.test.tsindex a39695e58..d43d85e55 100644--- a/packages/app/src/lib/install-client-log-forwarder.test.ts+++ b/packages/app/src/lib/install-client-log-forwarder.test.ts@@ -228,6 +228,109 @@ describe('installClientLogForwarder', () => {expect((entry?.message as string).length).toBeLessThanOrEqual(8192);});+ test('a failed POST is counted and carried as droppedSinceLastFlush on the next batch', async () => {+ let failNext = true;+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>+ failNext+ ? Promise.reject(new Error('network down'))+ : Promise.resolve(new Response(null, { status: 200 })),+ );+ const { con } = install(fetchSpy);++ con.warn('lost-1');+ con.warn('lost-2');+ handle?.flushNow();+ await new Promise((r) => setTimeout(r, 0)); // let the rejection handler run++ failNext = false;+ con.warn('delivered');+ handle?.flushNow();+ expect(fetchSpy).toHaveBeenCalledTimes(2);+ const body = bodyOf(fetchSpy) as { entries: unknown[]; droppedSinceLastFlush?: number };+ expect(body.entries).toHaveLength(1);+ expect(body.droppedSinceLastFlush).toBe(2);+ });++ test('a non-2xx response counts the batch as dropped', async () => {+ let reject = true;+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>+ Promise.resolve(new Response(null, { status: reject ? 500 : 200 })),+ );+ const { con } = install(fetchSpy);++ con.warn('rejected');+ handle?.flushNow();+ await new Promise((r) => setTimeout(r, 0));++ reject = false;+ con.warn('delivered');+ handle?.flushNow();+ const body = bodyOf(fetchSpy) as { droppedSinceLastFlush?: number };+ expect(body.droppedSinceLastFlush).toBe(1);+ });++ test('a sustained failing burst past the entry cap preserves the accumulated drop count on recovery', async () => {+ // The reconnect-storm scenario the feature targets: entries arrive faster+ // than they can be delivered while the server is unreachable. Each auto-flush+ // at the entry cap drains the queue and fails its POST — the failed-batch+ // accounting must accumulate across cycles and ride the first delivered batch+ // once the server recovers. (The ring-overflow `shift` in `enqueue` is not+ // exercised here: the flush-at-cap drains the queue at exactly the cap, so it+ // never grows past it — the failed-POST path is the real bound.)+ let failNext = true;+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>+ failNext+ ? Promise.reject(new Error('network down'))+ : Promise.resolve(new Response(null, { status: 200 })),+ );+ const { con } = install(fetchSpy);++ // Two full cap-sized batches, all failing → two auto-flush cycles.+ for (let i = 0; i < RENDERER_LOG_MAX_ENTRIES * 2; i++) con.warn(`storm-${i}`);+ await new Promise((r) => setTimeout(r, 0)); // let both rejection handlers run++ failNext = false;+ con.warn('delivered');+ handle?.flushNow();+ const body = bodyOf(fetchSpy) as { entries: unknown[]; droppedSinceLastFlush?: number };+ expect(body.entries).toHaveLength(1);+ expect(body.droppedSinceLastFlush).toBe(RENDERER_LOG_MAX_ENTRIES * 2);+ });++ test('drop count resets after a delivered batch (field absent when zero)', async () => {+ let failNext = true;+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>+ failNext+ ? Promise.reject(new Error('network down'))+ : Promise.resolve(new Response(null, { status: 200 })),+ );+ const { con } = install(fetchSpy);++ con.warn('lost');+ handle?.flushNow();+ await new Promise((r) => setTimeout(r, 0));++ failNext = false;+ con.warn('carries the count');+ handle?.flushNow();+ await new Promise((r) => setTimeout(r, 0)); // let the success handler subtract++ con.warn('clean batch');+ handle?.flushNow();+ const body = bodyOf(fetchSpy) as { entries: unknown[]; droppedSinceLastFlush?: number };+ expect(body.entries).toHaveLength(1);+ expect(body.droppedSinceLastFlush).toBeUndefined();+ });++ test('no droppedSinceLastFlush field when nothing was dropped', () => {+ const fetchSpy = makeFetchSpy();+ const { con } = install(fetchSpy);+ con.warn('all good');+ handle?.flushNow();+ const body = bodyOf(fetchSpy) as { droppedSinceLastFlush?: number };+ expect(body.droppedSinceLastFlush).toBeUndefined();+ });+test('uninstall restores console and clears the marker (fresh install works)', () => {const fetchSpy = makeFetchSpy();const con = makeFakeConsole();diff --git a/packages/app/src/lib/install-client-log-forwarder.ts b/packages/app/src/lib/install-client-log-forwarder.tsindex 5237b5db6..8a14be77d 100644--- a/packages/app/src/lib/install-client-log-forwarder.ts+++ b/packages/app/src/lib/install-client-log-forwarder.ts@@ -145,6 +145,12 @@ export function installClientLogForwarder(// Set while flushing so neither the flush path nor any transitive console// call it triggers gets re-captured (recursion guard).let inForward = false;+ // Entries lost since the last delivered batch (ring overflow + failed+ // POSTs). Carried as `droppedSinceLastFlush` on the next successful batch so+ // the persisted log records that a gap exists — the drops cluster exactly+ // when diagnostics matter most (reconnect storms), and a silent gap reads+ // as "nothing happened".+ let droppedSinceLastFlush = 0;const original: ConsoleLike = {log: con.log.bind(con),@@ -161,19 +167,43 @@ export function installClientLogForwarder(if (queue.length === 0) return;const entries = queue.splice(0, RENDERER_LOG_MAX_ENTRIES);pendingBytes = 0;+ // Snapshot the drop count at send time: on delivery only this snapshot is+ // subtracted (not a reset to 0), so drops that accrue while the POST is in+ // flight survive to the next batch.+ const droppedAtSend = droppedSinceLastFlush;inForward = true;try {void doFetch('/api/client-logs', {method: 'POST',headers: { 'content-type': 'application/json' },keepalive: true,- body: JSON.stringify({ entries }),- }).catch(() => {- // Network failure — drop. Never surface; never console.* here (would- // re-capture). The entries are already removed from the queue.- });+ body: JSON.stringify(+ droppedAtSend > 0 ? { entries, droppedSinceLastFlush: droppedAtSend } : { entries },+ ),+ }).then(+ (res) => {+ if (res.ok) {+ // Clamp at zero: `inForward` is released in the `finally` before this+ // promise settles, so a second flush can fire and snapshot the same+ // non-zero `droppedAtSend`. Two overlapping 2xx deliveries would then+ // each subtract it and drive the counter negative, suppressing the+ // next genuine gap marker. The clamp keeps double-reporting from+ // going below zero.+ droppedSinceLastFlush = Math.max(0, droppedSinceLastFlush - droppedAtSend);+ } else {+ // Non-2xx: the server rejected the batch; these entries are gone.+ droppedSinceLastFlush += entries.length;+ }+ },+ () => {+ // Network failure — drop. Never surface; never console.* here (would+ // re-capture). The entries are already removed from the queue.+ droppedSinceLastFlush += entries.length;+ },+ );} catch {// Synchronous failure (e.g. serialization) — drop the batch.+ droppedSinceLastFlush += entries.length;} finally {inForward = false;}@@ -185,7 +215,10 @@ export function installClientLogForwarder(// Bounded ring — drop oldest under sustained backpressure.if (queue.length > RENDERER_LOG_MAX_ENTRIES) {const dropped = queue.shift();- if (dropped) pendingBytes -= estimateEntryBytes(dropped);+ if (dropped) {+ pendingBytes -= estimateEntryBytes(dropped);+ droppedSinceLastFlush += 1;+ }}// Flush on entry count OR byte budget — the byte cap keeps each POST under// the browser's ~64KB `keepalive` limit so unload-time flushes aren'tdiff --git a/packages/app/tests/integration/api-error-envelope/metrics-agent-effects.test.ts b/packages/app/tests/integration/api-error-envelope/metrics-agent-effects.test.tsnew file mode 100644index 000000000..c44e16182--- /dev/null+++ b/packages/app/tests/integration/api-error-envelope/metrics-agent-effects.test.ts@@ -0,0 +1,107 @@+/**+ * Per-handler narrow-integration smoke test for `handleMetricsAgentEffects`.+ *+ * Asserts the canonical RFC 9457 wire shape for+ * `GET /api/metrics/agent-effects`. This handler shares the same+ * auth-before-method-dispatch ordering as `handleMetricsAgentPresence`+ * (loopback gate → host-allowlist gate → method check) so a bad Host never+ * leaks "verb the endpoint expects" via 405.+ *+ * Coverage:+ * - happy path: 200 + `application/json` + body parses against+ * `MetricsAgentEffectsSuccessSchema`, no `ok` discriminator.+ * - populated path: an agent write is captured into the doc's ring buffer+ * and surfaces as a summarized per-doc block (character counts only —+ * never the raw delta text).+ * - DNS-rebinding Host → 403 `urn:ok:error:host-not-allowed` (must+ * emit BEFORE the method check).+ * - method-not-allowed on POST → 405 `urn:ok:error:method-not-allowed`+ * with `Allow: GET`.+ */++import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import {+ MetricsAgentEffectsSuccessSchema,+ ProblemDetailsSchema,+} from '@inkeep/open-knowledge-core';+import { HARNESS_BOOT_TIMEOUT_MS } from '../harness-boot-timeout';+import { fetchWithHostHeader } from '../host-header-request.test-helper';+import { createTestServer, type TestServer } from '../test-harness';++let server: TestServer;++beforeAll(async () => {+ server = await createTestServer();+}, HARNESS_BOOT_TIMEOUT_MS);++afterAll(async () => {+ await server.cleanup();+});++describe('metrics-agent-effects envelope (RFC 9457)', () => {+ test('happy path emits flat success body with application/json', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-effects`);+ expect(res.status).toBe(200);+ expect(res.headers.get('content-type')).toBe('application/json');++ const body = await res.json();+ expect(MetricsAgentEffectsSuccessSchema.safeParse(body).success).toBe(true);+ expect((body as Record<string, unknown>).ok).toBeUndefined();+ });++ test('an agent write surfaces as a summarized per-doc block (no raw delta text)', async () => {+ const docName = `agent-effects-populated-${crypto.randomUUID().slice(0, 8)}`;+ const written = '# Agent effects probe\n';+ const writeRes = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ markdown: written, position: 'replace', docName }),+ });+ expect(writeRes.status).toBe(200);++ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-effects`);+ expect(res.status).toBe(200);+ const parsed = MetricsAgentEffectsSuccessSchema.safeParse(await res.json());+ expect(parsed.success).toBe(true);+ if (!parsed.success) return;++ const block = parsed.data.effects.find((b) => b['doc.name'] === docName);+ expect(block).toBeDefined();+ expect(block?.entries.length).toBeGreaterThan(0);+ const entry = block?.entries[0];+ expect(entry?.insertedChars).toBeGreaterThan(0);+ // Summaries only: the response must never carry the written text.+ expect(JSON.stringify(parsed.data)).not.toContain('Agent effects probe');+ });++ test('DNS-rebinding Host emits 403 urn:ok:error:host-not-allowed BEFORE method check', async () => {+ const res = await fetchWithHostHeader(+ `http://127.0.0.1:${server.port}/api/metrics/agent-effects`,+ 'evil.example.com',+ { method: 'POST' },+ );+ // Auth-before-method-dispatch ordering: bad Host → 403, NOT 405.+ expect(res.status).toBe(403);+ expect(res.headers.get('content-type')).toBe('application/problem+json');++ const parsed = ProblemDetailsSchema.safeParse(await res.json());+ expect(parsed.success).toBe(true);+ if (parsed.success) {+ expect(parsed.data.type).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('method-not-allowed on POST (with valid Host) emits problem+json with Allow: GET', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-effects`, {+ method: 'POST',+ });+ expect(res.status).toBe(405);+ expect(res.headers.get('allow')).toBe('GET');++ const parsed = ProblemDetailsSchema.safeParse(await res.json());+ expect(parsed.success).toBe(true);+ if (parsed.success) {+ expect(parsed.data.type).toBe('urn:ok:error:method-not-allowed');+ }+ });+});diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.tsindex da42fb579..eaa92a3a7 100644--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts@@ -188,6 +188,10 @@ const EXEMPT_HANDLERS = new Set(['handleMetricsReconciliation','handleMetricsParseHealth','handleMetricsAgentPresence',+ // `/api/metrics/agent-effects` — GET-only loopback + host-gated diagnostic+ // (per-doc agent-effects ring-buffer summaries). Read path, no writes,+ // nothing to attribute — same posture as `handleMetricsAgentPresence`.+ 'handleMetricsAgentEffects',// `/api/client-logs` — web/browser renderer console-log ingest. Writes only// to the `renderer` pino log (diagnostics), no Y.Docs / agent content; gated// by `checkLocalOpSecurity` like the local-op handlers. No identity needed.diff --git a/packages/app/tests/integration/client-logs-endpoint.test.ts b/packages/app/tests/integration/client-logs-endpoint.test.tsindex 9d7b04777..902cb33db 100644--- a/packages/app/tests/integration/client-logs-endpoint.test.ts+++ b/packages/app/tests/integration/client-logs-endpoint.test.ts@@ -57,6 +57,23 @@ describe('POST /api/client-logs', () => {expect(body.accepted).toBe(2);});+ test('accepts a batch carrying a droppedSinceLastFlush gap marker', async () => {+ const res = await postLogs({+ entries: [{ level: 'warn', message: 'after a reconnect storm' }],+ droppedSinceLastFlush: 7,+ });+ expect(res.status).toBe(200);+ expect(((await res.json()) as { accepted: number }).accepted).toBe(1);+ });++ test('rejects a negative droppedSinceLastFlush with 400', async () => {+ const res = await postLogs({+ entries: [{ level: 'warn', message: 'x' }],+ droppedSinceLastFlush: -1,+ });+ expect(res.status).toBe(400);+ });+test('accepts an empty batch (accepted: 0)', async () => {const res = await postLogs({ entries: [] });expect(res.status).toBe(200);diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.tsindex 935b0ac2d..8f5fa0023 100644--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts@@ -125,6 +125,11 @@ const EXEMPT_HANDLERS = new Set(['handleMetricsReconciliation','handleMetricsParseHealth','handleMetricsAgentPresence',+ // `/api/metrics/agent-effects` — GET-only loopback + host-gated diagnostic+ // summarizing the per-doc `Y.Map('agent-effects')` ring buffers. Reads only;+ // targets no Y.Doc write, so the per-doc conflict gate does not apply — same+ // posture as its `handleMetricsAgentPresence` sibling.+ 'handleMetricsAgentEffects',// `/api/__embed-detect` — read-only loopback + host-gated diagnostic for the// embedded-viewer detection spikes; reads the in-process UA ring buffer and// returns boolean signals, targets no Y.Doc, so the per-doc conflict gatediff --git a/packages/cli/src/diagnose/bundle-redact.test.ts b/packages/cli/src/diagnose/bundle-redact.test.tsindex 948553238..2fe6333b7 100644--- a/packages/cli/src/diagnose/bundle-redact.test.ts+++ b/packages/cli/src/diagnose/bundle-redact.test.ts@@ -358,6 +358,78 @@ describe('redactStagedBundle — contentDir substitution', () => {expect(Object.values(result.docNameMap)).toContain('live-doc');});+ test('hashes the real `currentDoc` field the presence endpoint emits', () => {+ // The live `/api/metrics/agent-presence` wire body carries the doc path+ // under `currentDoc`, not `doc.name`. The walker must hash that exact key+ // so a staged presence artifact never leaks the doc a human is editing.+ const stagingDir = makeStagingDir();+ const contentDir = '/Users/test/notes';+ writeStaged(+ stagingDir,+ 'state/agent-presence.json',+ `${JSON.stringify({+ presence: {+ 'agent-a1': {+ displayName: 'Claude',+ icon: 'claude',+ color: '#abc',+ currentDoc: 'meetings/secret-standup',+ mode: 'writing',+ ts: 1,+ },+ },+ })}`,+ );++ const result = redactStagedBundle({ stagingDir, contentDir });++ const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));+ expect(after.presence['agent-a1'].currentDoc).toMatch(/^doc:[a-f0-9]{8}$/);+ expect(JSON.stringify(after)).not.toContain('meetings/secret-standup');+ expect(Object.values(result.docNameMap)).toContain('meetings/secret-standup');+ });++ test('leaves a null `currentDoc` untouched (only strings hash)', () => {+ const stagingDir = makeStagingDir();+ const contentDir = '/Users/test/notes';+ writeStaged(+ stagingDir,+ 'state/agent-presence.json',+ `${JSON.stringify({+ presence: { 'agent-a1': { currentDoc: null, mode: 'idle', ts: 1 } },+ })}`,+ );++ redactStagedBundle({ stagingDir, contentDir });++ const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));+ expect(after.presence['agent-a1'].currentDoc).toBeNull();+ });++ test('hashes doc.name values in state/agent-effects.json via the walker pass', () => {+ const stagingDir = makeStagingDir();+ const contentDir = '/Users/test/notes';+ writeStaged(+ stagingDir,+ 'state/agent-effects.json',+ `${JSON.stringify({+ effects: [+ {+ 'doc.name': 'meetings/standup',+ entries: [{ sessionId: 'agent-a1', agentType: 'claude', ts: 1, insertedChars: 4 }],+ },+ ],+ })}`,+ );++ const result = redactStagedBundle({ stagingDir, contentDir });++ const after = JSON.parse(readStaged(stagingDir, 'state/agent-effects.json'));+ expect(after.effects[0]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);+ expect(after.effects[0].entries[0].sessionId).toBe('agent-a1');+ expect(Object.values(result.docNameMap)).toContain('meetings/standup');+ });+test('strings that do not include contentDir are passed through verbatim', () => {const stagingDir = makeStagingDir();const contentDir = '/Users/test/notes';diff --git a/packages/cli/src/diagnose/bundle-redact.ts b/packages/cli/src/diagnose/bundle-redact.tsindex 045ad5d32..79e95bdc7 100644--- a/packages/cli/src/diagnose/bundle-redact.ts+++ b/packages/cli/src/diagnose/bundle-redact.ts@@ -31,8 +31,12 @@ const HASH_HEX_LEN = 8;// Keys whose values are treated as doc-name-shaped. The OTLP attribute pair// form sets `key` to one of these and stores the value under `value.stringValue`;// the Pino flat form sets the key directly on the log record. Single source-// for both shapes — extending DOC_NAME_KEYS covers both at once.-const DOC_NAME_KEYS = new Set(['doc.name']);+// for both shapes — extending DOC_NAME_KEYS covers both at once. `currentDoc`+// is the workspace-relative doc path carried by `agent-presence.json` entries;+// hashing it keeps a redacted presence artifact from leaking the doc a human+// was editing (same anonymization guarantee the `doc.name`-keyed effects+// artifact already gets).+const DOC_NAME_KEYS = new Set(['doc.name', 'currentDoc']);export interface RedactStagedBundleOpts {/** Absolute path to the staging dir (contains telemetry/, logs/, state/). */@@ -263,10 +267,10 @@ function walkDirFiles(dir: string): string[] {}}-// State files that are JSON-shaped get a full walker pass (agent-presence may-// carry per-agent doc.name fields; runtime.json may carry the contentDir).-// Other state files get substring-only substitution.-const STATE_JSON_FILES = new Set(['agent-presence.json', 'runtime.json']);+// State files that are JSON-shaped get a full walker pass (agent-presence and+// agent-effects may carry per-doc `doc.name` fields; runtime.json may carry+// the contentDir). Other state files get substring-only substitution.+const STATE_JSON_FILES = new Set(['agent-presence.json', 'agent-effects.json', 'runtime.json']);export function redactStagedBundle(opts: RedactStagedBundleOpts): RedactStagedBundleResult {const ctx: RedactCtx = {diff --git a/packages/cli/src/diagnose/bundle.test.ts b/packages/cli/src/diagnose/bundle.test.tsindex 7f8b60c76..37385c8db 100644--- a/packages/cli/src/diagnose/bundle.test.ts+++ b/packages/cli/src/diagnose/bundle.test.ts@@ -44,7 +44,9 @@ afterEach(() => {function makeDeterministicDeps(over: Partial<CollectBundleDeps> = {}): CollectBundleDeps {return {fetchAgentPresence: async () => null,+ fetchAgentEffects: async () => null,readShadowHead: () => null,+ readCheckpointRefs: () => null,now: () => new Date('2026-05-28T14:22:01.000Z'),okVersion: () => '0.7.99',readDesktopEnv: () => null,@@ -310,6 +312,48 @@ describe('collectBundle — server status', () => {collected.cleanup();});+ test('lock present + agent-effects 2xx → agent-effects.json staged', async () => {+ const contentDir = makeTmpDir();+ writeAt(+ contentDir,+ '.ok/local/server.lock',+ JSON.stringify({ pid: 1, port: 4711, hostname: 'h', startedAt: 't', worktreeRoot: '/' }),+ );+ let queriedPort = -1;+ const deps = makeDeterministicDeps({+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),+ fetchAgentEffects: async (port) => {+ queriedPort = port;+ return JSON.stringify({ effects: [] });+ },+ });+ const collected = await collectBundle({ contentDir, deps });++ expect(queriedPort).toBe(4711);+ const effectsPath = join(collected.stagingDir, 'state', 'agent-effects.json');+ expect(existsSync(effectsPath)).toBe(true);+ expect(JSON.parse(readFileSync(effectsPath, 'utf-8'))).toEqual({ effects: [] });+ collected.cleanup();+ });++ test('agent-effects failure never affects serverStatus (presence is the probe)', async () => {+ const contentDir = makeTmpDir();+ writeAt(+ contentDir,+ '.ok/local/server.lock',+ JSON.stringify({ pid: 1, port: 4711, hostname: 'h', startedAt: 't', worktreeRoot: '/' }),+ );+ const deps = makeDeterministicDeps({+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),+ fetchAgentEffects: async () => null,+ });+ const collected = await collectBundle({ contentDir, deps });++ expect(collected.manifest.serverStatus).toBe('running');+ expect(existsSync(join(collected.stagingDir, 'state', 'agent-effects.json'))).toBe(false);+ collected.cleanup();+ });+test('corrupt lock → not-running, lock still staged for forensics', async () => {const contentDir = makeTmpDir();writeAt(contentDir, '.ok/local/server.lock', 'not json {');@@ -345,6 +389,28 @@ describe('collectBundle — state files', () => {collected.cleanup();});+ test('checkpoint-refs.txt is written when readCheckpointRefs returns content', async () => {+ const contentDir = makeTmpDir();+ const listing =+ 'refs/checkpoints/main/deadbee\t2026-05-28T14:00:00+00:00\tcheckpoint: Before concurrent merge @ 2026-05-28T14:00:00.000Z\n';+ const deps = makeDeterministicDeps({+ readCheckpointRefs: () => listing,+ });+ const collected = await collectBundle({ contentDir, deps });+ expect(readFileSync(join(collected.stagingDir, 'state', 'checkpoint-refs.txt'), 'utf-8')).toBe(+ listing,+ );+ expect(collected.manifest.files.map((f) => f.path)).toContain('state/checkpoint-refs.txt');+ collected.cleanup();+ });++ test('checkpoint-refs.txt is omitted when readCheckpointRefs returns null', async () => {+ const contentDir = makeTmpDir();+ const collected = await collectBundle({ contentDir, deps: makeDeterministicDeps() });+ expect(existsSync(join(collected.stagingDir, 'state', 'checkpoint-refs.txt'))).toBe(false);+ collected.cleanup();+ });+test('last-server-exit.json is staged when the desktop host wrote one', async () => {const contentDir = makeTmpDir();const body = `${JSON.stringify(diff --git a/packages/cli/src/diagnose/bundle.ts b/packages/cli/src/diagnose/bundle.tsindex ba63ba839..26f5e037e 100644--- a/packages/cli/src/diagnose/bundle.ts+++ b/packages/cli/src/diagnose/bundle.ts@@ -202,12 +202,28 @@ export interface CollectBundleDeps {* on any failure (network, timeout, non-2xx).*/fetchAgentPresence?: (port: number) => Promise<string | null>;+ /**+ * Fetch the running server's `GET /api/metrics/agent-effects` response+ * (per-doc agent activity ring-buffer summaries), within the 1s budget.+ * Returns the response body string on 2xx, or `null` on any failure.+ * Best-effort like agent-presence; a `null` never affects `serverStatus`.+ */+ fetchAgentEffects?: (port: number) => Promise<string | null>;/*** Read the last 50 entries of the shadow repo log at* `<contentDir>/.git/ok/`. Returns the stdout string or `null` if the* shadow repo is missing or git fails.*/readShadowHead?: (contentDir: string) => string | null;+ /**+ * List the most recent `refs/checkpoints/*` refs of the shadow repo at+ * `<contentDir>/.git/ok/` — the content-loss / rescue recovery snapshots.+ * One tab-separated line per ref: ref name, creation date, commit subject+ * (the subject is a content-free label; the commit BODY, which can carry+ * doc names and lost content, is deliberately not read). Returns the+ * listing string or `null` if the shadow repo is missing or git fails.+ */+ readCheckpointRefs?: (contentDir: string) => string | null;/** Returns the current timestamp. Override in tests for determinism. */now?: () => Date;/** Returns the OK CLI's package version. */@@ -322,6 +338,7 @@ export const _pathHelpersForTests = {const AGENT_PRESENCE_TIMEOUT_MS = 1000;const SHADOW_GIT_LOG_LIMIT = 50;+const CHECKPOINT_REF_LIMIT = 50;async function defaultFetchAgentPresence(port: number): Promise<string | null> {try {@@ -338,6 +355,21 @@ async function defaultFetchAgentPresence(port: number): Promise<string | null> {}}+async function defaultFetchAgentEffects(port: number): Promise<string | null> {+ try {+ const response = await fetch(`http://127.0.0.1:${port}/api/metrics/agent-effects`, {+ signal: AbortSignal.timeout(AGENT_PRESENCE_TIMEOUT_MS),+ });+ if (!response.ok) return null;+ return await response.text();+ } catch {+ // Same all-failures-collapse-to-null posture as agent-presence — a+ // server without the endpoint (older version) or not running must not+ // fail the bundle.+ return null;+ }+}+function defaultReadShadowHead(contentDir: string): string | null {const shadowDir = join(contentDir, '.git', 'ok');if (!existsSync(shadowDir)) return null;@@ -350,6 +382,31 @@ function defaultReadShadowHead(contentDir: string): string | null {return result.stdout ?? '';}+function defaultReadCheckpointRefs(contentDir: string): string | null {+ const shadowDir = join(contentDir, '.git', 'ok');+ if (!existsSync(shadowDir)) return null;+ // `%(contents:subject)` only: checkpoint commit bodies carry an+ // `ok-checkpoint-v1` JSON line with the doc name and (for merge-loss+ // checkpoints) lost-content substrings — the subject is a content-free+ // label, so restricting the format keeps the artifact safe to stage as+ // plain text under the same redaction rules as shadow-head.txt.+ const result = spawnSync(+ 'git',+ [+ '-C',+ shadowDir,+ 'for-each-ref',+ '--sort=-creatordate',+ `--count=${CHECKPOINT_REF_LIMIT}`,+ '--format=%(refname)%09%(creatordate:iso-strict)%09%(contents:subject)',+ 'refs/checkpoints/',+ ],+ withHiddenWindowsConsole({ encoding: 'utf-8', timeout: 2000 }),+ );+ if (result.error || result.status !== 0) return null;+ return result.stdout ?? '';+}+export function defaultReadDesktopEnv(): DesktopMetadata | null {const electronVersion = process.env.OK_DESKTOP_VERSION;const packagedRaw = process.env.OK_DESKTOP_PACKAGED;@@ -569,7 +626,9 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedBconst projectDir = resolve(opts.projectDir ?? opts.contentDir);const deps = opts.deps ?? {};const fetchAgentPresence = deps.fetchAgentPresence ?? defaultFetchAgentPresence;+ const fetchAgentEffects = deps.fetchAgentEffects ?? defaultFetchAgentEffects;const readShadowHead = deps.readShadowHead ?? defaultReadShadowHead;+ const readCheckpointRefs = deps.readCheckpointRefs ?? defaultReadCheckpointRefs;const now = deps.now ?? (() => new Date());const okVersion = deps.okVersion ?? (() => PACKAGE_VERSION);const readDesktopEnv = deps.readDesktopEnv ?? defaultReadDesktopEnv;@@ -621,6 +680,13 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB} else {serverStatusReason = `agent-presence endpoint at :${lockPort} unreachable`;}+ // Agent-effects ring-buffer summaries — best effort, never affects+ // serverStatus (presence remains the liveness probe; an older server+ // without this endpoint is still "running").+ const agentEffects = await fetchAgentEffects(lockPort);+ if (agentEffects !== null) {+ writeFileSync(join(stagingDir, 'state', 'agent-effects.json'), agentEffects);+ }}// Shadow-repo head — best effort.@@ -629,6 +695,16 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedBwriteFileSync(join(stagingDir, 'state', 'shadow-head.txt'), shadowHead);}+ // Recovery-checkpoint refs (`refs/checkpoints/*`) — best effort. The+ // default-branch shadow log above never shows these one-shot refs, yet+ // they are the primary artifact for the content-loss bug class: their+ // presence, kind-bearing subjects, and timestamps tell the recipient+ // whether (and when) the bridge detected potential loss.+ const checkpointRefs = readCheckpointRefs(contentDir);+ if (checkpointRefs !== null) {+ writeFileSync(join(stagingDir, 'state', 'checkpoint-refs.txt'), checkpointRefs);+ }+// last-spawn-error.log (Electron host writes this when a spawn fails).stageFileIfPresent(join(lockDir, 'last-spawn-error.log'),diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex 8f9d95287..c014b1413 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,4 +1,3 @@-import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 8bfdb40cd..005627195 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,4 +1,3 @@-import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex c18c086d5..8890f6739 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,4 +1,3 @@-import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';const LEADING_BOUNDARY_RE = /^(?:\r?\n)+/;diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsindex 463e89595..9d9c244b0 100644--- a/packages/core/src/bridge/growth-detect.ts+++ b/packages/core/src/bridge/growth-detect.ts@@ -1,4 +1,3 @@-const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex 3c927eb47..3ab9cc6ef 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -38,7 +38,6 @@ function mergeThreeWayImpl(baseline: string, userText: string, agentText: stringreturn parts.join('\n');}-export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex 3f0880aa5..4b8890476 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,4 +1,3 @@-const COMMONMARK_ESCAPE_RE = /\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/g;const TABLE_ALIGN_ROW_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/;diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.tsindex 0be5203e4..754dc5cc2 100644--- a/packages/core/src/bridge/pm-structural-equivalence.ts+++ b/packages/core/src/bridge/pm-structural-equivalence.ts@@ -32,7 +32,6 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };const BR_LITERAL_RE = /^<br\s*\/?>$/i;-interface DegradeEntry {readonly label: string;readonly severity: ToleranceClassSeverity;@@ -128,7 +127,6 @@ export interface ComparePmStructuralOptions {ignoreAttrs?: (attrKey: string) => boolean;}-/** Rebuild a node with `fn` applied to each child; identity when childless.* Shared by the degrade canonicalizers so none re-implements the walk. */function mapChildren(@@ -250,7 +248,6 @@ function applyDegrades(tree: PmStructuralNode): {return { normalized: current, fired };}-export function comparePmStructural(expected: PmStructuralNode,actual: PmStructuralNode,diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.tsindex dca644141..af20de1e2 100644--- a/packages/core/src/bridge/subsequence.ts+++ b/packages/core/src/bridge/subsequence.ts@@ -1,4 +1,3 @@-/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):* insertions in `haystack` are free; any dropped or substituted `needle` byte* fails. */diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 950792556..666c3e892 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -561,6 +561,10 @@ export {AgentActivitySuccessSchema,type AgentBurstDiffSuccess,AgentBurstDiffSuccessSchema,+ AgentEffectEntrySchema,+ type AgentEffectEntryWire,+ AgentEffectsDocSchema,+ type AgentEffectsDocWire,type AgentPatchRequest,AgentPatchRequestSchema,type AgentPatchSuccess,@@ -736,6 +740,8 @@ export {LocalOpOkInitRequestSchema,type LocalOpOkInitResponse,LocalOpOkInitResponseSchema,+ type MetricsAgentEffectsSuccess,+ MetricsAgentEffectsSuccessSchema,type MetricsAgentPresenceSuccess,MetricsAgentPresenceSuccessSchema,type MetricsParseHealthSuccess,diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex a363dfd54..83d47404a 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,4 +1,3 @@-import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 47f0d07e4..193e286b0 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex b6299a948..ece5c02a1 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,4 +1,3 @@-import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex acd398aa6..54774764a 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex fb5ac8e8a..c7518d614 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,4 +1,3 @@-const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 6931623c7..00f5771ee 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,4 +1,3 @@-import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -9,7 +8,6 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}-interface GfmExample {section: string;markdown: string;@@ -19,7 +17,6 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}-interface MdxCrashEntry {id: string;input: string;@@ -71,7 +68,6 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}-export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -80,7 +76,6 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}-export interface NgPinnedCase {id: string;name: string;@@ -97,7 +92,6 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}-export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex daa3ef82b..8b1eb8519 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,4 +1,3 @@-import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -11,7 +10,6 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;-function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -38,7 +36,6 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}-const WORDS = ['lorem','ipsum',@@ -156,7 +153,6 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}-type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -195,7 +191,6 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}-function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 32c055c5b..420dc0fe5 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,7 +7,6 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';-export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 283913255..2653473da 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,4 +1,3 @@-export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex 6319f264f..f55912407 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex 2f082e6d0..78fdfeb02 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,4 +1,3 @@-import type { Root as HastRoot } from 'hast';import type { Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -76,8 +75,7 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified()- .use(rehypeParse, { fragment: true });+ const processor = unified().use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 994eb6917..706fa9afb 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,4 +1,3 @@-import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex fc30bda02..8b36807fd 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,4 +1,3 @@-import {type FromProseMirrorOptions,fromPmMark,@@ -197,7 +196,6 @@ export class MarkdownManager {}}-const registry = createRegistry();function destructureAttrs(@@ -246,7 +244,6 @@ function destructureAttrs(return result;}-function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -266,7 +263,6 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecreturn freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;}-function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -335,7 +331,6 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}-import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -582,7 +577,6 @@ function buildMdastToPmHandlers(}));}-if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -663,7 +657,6 @@ function buildMdastToPmHandlers(}));}-if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -942,7 +935,6 @@ function buildMdastToPmHandlers(};}-const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1068,7 +1060,6 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}-function buildPmToMdastHandlers(schema: Schema,freshness: FreshnessCheckerHolder,diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.tsindex 207cd95c2..e78a1381d 100644--- a/packages/core/src/markdown/lint/config-schemas.ts+++ b/packages/core/src/markdown/lint/config-schemas.ts@@ -29,7 +29,6 @@ const fullPluginShape = Object.fromEntries(LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),) as z.ZodRawShape;-export const LinterConfigSchema = z.object({enabled: z.boolean(),plugins: z.object(fullPluginShape),diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.tsindex a51f2ffb0..d48eea5e4 100644--- a/packages/core/src/markdown/lint/default-config.ts+++ b/packages/core/src/markdown/lint/default-config.ts@@ -6,7 +6,6 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSettingMD013: false,};-export function resolveMarkdownlintConfig(rules: Record<string, MarkdownlintRuleSetting> | undefined,): Configuration {diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.tsindex 3baacdeb7..d1a5ab4dc 100644--- a/packages/core/src/markdown/lint/index.ts+++ b/packages/core/src/markdown/lint/index.ts@@ -1,4 +1,3 @@-import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';import type { LintDiagnostic } from './types.ts';diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.tsindex 65a1b564c..1cd40ef3a 100644--- a/packages/core/src/markdown/lint/plugins.ts+++ b/packages/core/src/markdown/lint/plugins.ts@@ -1,4 +1,3 @@-import { z } from 'zod';import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';import { fixMarkdownText, runMarkdownlint } from './markdownlint-runner.ts';@@ -9,7 +8,6 @@ import {type MarkdownlintSlice,} from './types.ts';-const MarkdownlintRuleSettingSchema = z.union([z.boolean(),z.enum(MARKDOWNLINT_RULE_SEVERITIES),diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.tsindex 3651bd7eb..617f6e5b9 100644--- a/packages/core/src/markdown/lint/types.ts+++ b/packages/core/src/markdown/lint/types.ts@@ -1,4 +1,3 @@-export const LINT_PLUGIN_IDS = ['markdownlint'] as const;export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];@@ -42,7 +41,6 @@ export interface MarkdownlintSlice {rules: Record<string, MarkdownlintRuleSetting>;}-interface RuleOptionSpecBase {key: string;description: string;diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex bd79424c7..a5b511f25 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,4 +1,3 @@-import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex f84967798..679c72ef7 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,4 +1,3 @@-import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex df788a80d..8ce2b2492 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,4 +1,3 @@-import type { Element, Root as HastRoot, Text as HastText } from 'hast';import type { Root as MdastRoot, Text as MdastText } from 'mdast';import type { Handler } from 'mdast-util-to-hast';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex fa3cfcd86..bfd7e3109 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 17ed2b829..1a897fca8 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,4 +1,3 @@-import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex 7e4a9a48b..9864b3b60 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,7 +168,6 @@ export function parseRecursive(}}-interface VFilePlace {offset?: number;start?: { offset?: number };@@ -187,7 +186,6 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}-interface Region {start: number;end: number;@@ -211,7 +209,6 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}-export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -358,7 +355,6 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}-interface SourceBlock {src: string;start: number;@@ -456,7 +452,6 @@ function tryPerBlockFallback(};}-function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex 43d420187..e6ab4fd57 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,4 +1,3 @@-export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex e9e507469..7f2d5adca 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,4 +1,3 @@-import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex f8f5e8530..5a5e4c42a 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,4 +1,3 @@-import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex e5b4c9eba..0f399d34c 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,4 +1,3 @@-import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -477,8 +476,7 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- }- else if (first === '[') {+ } else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex ca225ce9b..db10fa54b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,4 +1,3 @@-import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 3a2524a9a..34068d103 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 2279a0189..93151d43b 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex a0f467c42..188f02d83 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4e8542a21..4ba2c3418 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex a3c96b24a..1a74b1272 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex e95cf43d6..de35e7b79 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,4 +1,3 @@-import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex ffdb4d5b5..b4be1b2ea 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex e2a96d1a7..3c8d88b7c 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex 0389575ac..cf2c9da8e 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,4 +1,3 @@-import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 8be632ba4..4d3250d3a 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,4 +1,3 @@-export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 542204403..46cc6a074 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,4 +1,3 @@-import type { Node as PmNode } from '@tiptap/pm/model';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { PropDef, SerializeContext } from '../registry/types.ts';diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex fe73659e6..be97d4d62 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,4 +1,3 @@-import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 7bce04302..8f4e9a41c 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,4 +1,3 @@-import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex c5bfd2386..cd245c38c 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,4 +1,3 @@-import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex ac9f5239b..d578476a7 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,4 +1,3 @@-const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex afd9936fe..6dad26200 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,7 +17,6 @@ declare module 'micromark-util-types' {}}-const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -261,7 +260,6 @@ export function wikiLinkSyntax(): Extension {};}-function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -387,7 +385,6 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};-const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {diff --git a/packages/core/src/schemas/api/client-logs.test.ts b/packages/core/src/schemas/api/client-logs.test.tsindex 837ba659a..b4e9bf065 100644--- a/packages/core/src/schemas/api/client-logs.test.ts+++ b/packages/core/src/schemas/api/client-logs.test.ts@@ -38,6 +38,17 @@ describe('ClientLogsRequestSchema', () => {expect(ClientLogsRequestSchema.safeParse({ entries }).success).toBe(false);});+ test('accepts an optional droppedSinceLastFlush count; rejects a negative one', () => {+ const entries = [{ level: 'info' as const, message: 'x' }];+ expect(ClientLogsRequestSchema.safeParse({ entries, droppedSinceLastFlush: 3 }).success).toBe(+ true,+ );+ expect(ClientLogsRequestSchema.safeParse({ entries }).success).toBe(true);+ expect(ClientLogsRequestSchema.safeParse({ entries, droppedSinceLastFlush: -1 }).success).toBe(+ false,+ );+ });+test('rejects an oversized message', () => {const result = ClientLogsRequestSchema.safeParse({entries: [{ level: 'error', message: 'a'.repeat(RENDERER_LOG_MAX_MESSAGE_BYTES + 1) }],diff --git a/packages/core/src/schemas/api/client-logs.ts b/packages/core/src/schemas/api/client-logs.tsindex 26d168548..73a978c6a 100644--- a/packages/core/src/schemas/api/client-logs.ts+++ b/packages/core/src/schemas/api/client-logs.ts@@ -33,10 +33,17 @@ export const ClientLogEntrySchema = z.loose() satisfies StandardSchemaV1;export type ClientLogEntry = z.infer<typeof ClientLogEntrySchema>;-/** Request body for `POST /api/client-logs` — a bounded batch of entries. */+/**+ * Request body for `POST /api/client-logs` — a bounded batch of entries.+ * `droppedSinceLastFlush` is the number of entries the client forwarder lost+ * since its last delivered batch (buffer overflow or failed POSTs — reconnect+ * storms are the typical cause); the server records it so the persisted log+ * carries an explicit gap marker instead of silently missing entries.+ */export const ClientLogsRequestSchema = z.object({entries: z.array(ClientLogEntrySchema).max(RENDERER_LOG_MAX_ENTRIES),+ droppedSinceLastFlush: z.number().int().min(0).optional(),}).loose() satisfies StandardSchemaV1;export type ClientLogsRequest = z.infer<typeof ClientLogsRequestSchema>;diff --git a/packages/core/src/schemas/api/metrics.test.ts b/packages/core/src/schemas/api/metrics.test.tsindex 7cbd36a21..b0e7d067e 100644--- a/packages/core/src/schemas/api/metrics.test.ts+++ b/packages/core/src/schemas/api/metrics.test.ts@@ -7,6 +7,7 @@ import {AgentBurstDiffSuccessSchema,AgentPresenceEntrySchema,InstalledAgentsSuccessSchema,+ MetricsAgentEffectsSuccessSchema,MetricsAgentPresenceSuccessSchema,MetricsParseHealthSuccessSchema,MetricsReconciliationSuccessSchema,@@ -326,6 +327,49 @@ describe('MetricsAgentPresenceSuccessSchema', () => {});});+describe('MetricsAgentEffectsSuccessSchema', () => {+ test('parses an empty effects list', () => {+ expect(MetricsAgentEffectsSuccessSchema.safeParse({ effects: [] }).success).toBe(true);+ });+ test('parses a populated per-doc block with summarized entries', () => {+ expect(+ MetricsAgentEffectsSuccessSchema.safeParse({+ effects: [+ {+ 'doc.name': 'meetings/standup',+ entries: [+ {+ sessionId: 'agent-a1',+ agentType: 'claude',+ ts: 1,+ insertedChars: 12,+ deletedChars: 0,+ },+ ],+ },+ ],+ }).success,+ ).toBe(true);+ });+ test('rejects body missing effects field', () => {+ expect(MetricsAgentEffectsSuccessSchema.safeParse({}).success).toBe(false);+ });+ test('rejects a negative character count', () => {+ expect(+ MetricsAgentEffectsSuccessSchema.safeParse({+ effects: [+ {+ 'doc.name': 'a',+ entries: [+ { sessionId: 's', agentType: 't', ts: 1, insertedChars: -1, deletedChars: 0 },+ ],+ },+ ],+ }).success,+ ).toBe(false);+ });+});+describe('InstalledAgentsSuccessSchema', () => {test('parses a populated boolean record', () => {expect(diff --git a/packages/core/src/schemas/api/metrics.ts b/packages/core/src/schemas/api/metrics.tsindex a836262f7..c9076e4ea 100644--- a/packages/core/src/schemas/api/metrics.ts+++ b/packages/core/src/schemas/api/metrics.ts@@ -1,10 +1,11 @@/*** metrics + agent activity + test handlers.*- * Eight handlers — `handleAgentActivity`, `handleAgentBurstDiff`,+ * Nine handlers — `handleAgentActivity`, `handleAgentBurstDiff`,* `handleTestReset`, `handleTestRescanBacklinks`,* `handleMetricsReconciliation`, `handleMetricsParseHealth`,- * `handleMetricsAgentPresence`, `handleInstalledAgentsRoute`. No new URN+ * `handleMetricsAgentPresence`, `handleMetricsAgentEffects`,+ * `handleInstalledAgentsRoute`. No new URN* tokens — every error path reuses existing tokens (`invalid-request`,* `reserved-doc-name`, `no-active-session`, `not-found`, `loopback-required`,* `host-not-allowed`, `invalid-origin`, `method-not-allowed`,@@ -166,6 +167,51 @@ export const MetricsAgentPresenceSuccessSchema = z.loose() satisfies StandardSchemaV1;export type MetricsAgentPresenceSuccess = z.infer<typeof MetricsAgentPresenceSuccessSchema>;+/**+ * One summarized agent-effects ring-buffer entry on+ * `MetricsAgentEffectsSuccessSchema.effects[].entries`. Deltas are reduced to+ * character counts — the diagnostic signal is who wrote how much to which doc+ * and when; the raw delta text (user content) never leaves the live doc via+ * this endpoint.+ */+export const AgentEffectEntrySchema = z+ .object({+ sessionId: z.string().min(1),+ agentType: z.string().min(1),+ ts: z.number().int().min(0),+ insertedChars: z.number().int().min(0),+ deletedChars: z.number().int().min(0),+ })+ .loose() satisfies StandardSchemaV1;+export type AgentEffectEntryWire = z.infer<typeof AgentEffectEntrySchema>;++/**+ * One per-doc block on `MetricsAgentEffectsSuccessSchema.effects`. The doc+ * name is carried under the literal key `doc.name` — the same key the+ * diagnostics-bundle redactor hashes — so a staged copy of this response is+ * anonymized by the existing pass without a redactor change.+ */+export const AgentEffectsDocSchema = z+ .object({+ 'doc.name': z.string().min(1),+ entries: z.array(AgentEffectEntrySchema),+ })+ .loose() satisfies StandardSchemaV1;+export type AgentEffectsDocWire = z.infer<typeof AgentEffectsDocSchema>;++/**+ * Success response for `GET /api/metrics/agent-effects`. Aggregates the+ * bounded per-doc `agent-effects` ring buffers across currently-loaded docs+ * (never force-loads unloaded ones). Loopback + Host-allowlist gated like+ * `/api/metrics/agent-presence`.+ */+export const MetricsAgentEffectsSuccessSchema = z+ .object({+ effects: z.array(AgentEffectsDocSchema),+ })+ .loose() satisfies StandardSchemaV1;+export type MetricsAgentEffectsSuccess = z.infer<typeof MetricsAgentEffectsSuccessSchema>;+/*** Success response for `GET /api/installed-agents`. Returns a flat boolean* record keyed by agent scheme name (`claude` / `codex` / `cursor`). Thediff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 4cefaaec8..6a70a0226 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -128,6 +128,8 @@ import {MANAGED_ARTIFACT_PREFIX_SKILL,MANAGED_ARTIFACT_PREFIX_TEMPLATE,MarkdownlintRuleWriteRequestSchema,+ type MetricsAgentEffectsSuccess,+ MetricsAgentEffectsSuccessSchema,MetricsAgentPresenceSuccessSchema,MetricsParseHealthSuccessSchema,MetricsReconciliationSuccessSchema,@@ -251,7 +253,7 @@ import busboy from 'busboy';import { fileTypeFromBuffer } from 'file-type';import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';import { z } from 'zod';-import { captureEffect } from './activity-log.ts';+import { captureEffect, type EffectValue } from './activity-log.ts';import { listAgentActivity, synthesizeVersionDiff } from './agent-activity.ts';import type { AgentFocusBroadcaster } from './agent-focus.ts';import { type AgentPresenceBroadcaster, BROADCASTER_EVICTION_MS } from './agent-presence.ts';@@ -8784,6 +8786,92 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {}}+ async function handleMetricsAgentEffects(+ req: IncomingMessage,+ res: ServerResponse,+ ): Promise<void> {+ // Diagnostic view of the per-doc `agent-effects` ring buffers, which+ // otherwise live only inside live Y.Docs and are invisible to bundles.+ // Loopback + Host-header gated with auth-before-method-dispatch ordering+ // — same pattern + rationale as `handleMetricsAgentPresence` (per-agent+ // identity plus per-doc write timing are local-editing-only signals).+ if (!isLoopbackAddress(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'metrics-agent-effects',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'metrics-agent-effects',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'metrics-agent-effects',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ // Tracks the doc being summarized so a throw in the per-doc reduction (e.g.+ // a malformed `EffectValue` from an older schema) names its source in the+ // catch log. Rides the `doc.name` key the bundle redactor hashes.+ let failingDocName: string | undefined;+ try {+ // Currently-loaded docs only — iterating `hocuspocus.documents` never+ // materializes an unloaded doc. The `share.has` probe avoids even+ // creating the lazy Y.Map placeholder on docs no agent ever wrote to.+ const effects: MetricsAgentEffectsSuccess['effects'] = [];+ for (const [effectsDocName, document] of hocuspocus.documents) {+ if (isSystemDoc(effectsDocName) || isConfigDoc(effectsDocName)) continue;+ if (!document.share.has('agent-effects')) continue;+ failingDocName = effectsDocName;+ const effectsMap = document.getMap<EffectValue>('agent-effects');+ if (effectsMap.size === 0) continue;+ // Deltas reduce to character counts: the diagnostic signal is who+ // wrote how much to which doc and when. Raw delta text is user+ // content and stays in the live doc.+ const entries = [...effectsMap.values()]+ .map((effect) => {+ let insertedChars = 0;+ let deletedChars = 0;+ for (const op of effect.delta) {+ if (typeof op.insert === 'string') insertedChars += op.insert.length;+ else if (op.insert !== undefined) insertedChars += 1;+ if (typeof op.delete === 'number') deletedChars += op.delete;+ }+ return {+ sessionId: effect.sessionId,+ agentType: effect.agent_type,+ ts: effect.timestamp,+ insertedChars,+ deletedChars,+ };+ })+ .sort((a, b) => a.ts - b.ts);+ // The doc name rides under the literal `doc.name` key — the key the+ // diagnostics-bundle redactor hashes — so a staged copy of this+ // response is anonymized by the existing pass.+ effects.push({ 'doc.name': effectsDocName, entries });+ }+ effects.sort((a, b) => a['doc.name'].localeCompare(b['doc.name']));+ successResponse(+ res,+ 200,+ MetricsAgentEffectsSuccessSchema,+ { effects },+ { handler: 'metrics-agent-effects' },+ );+ } catch (e) {+ log.error({ err: e, 'doc.name': failingDocName }, '[metrics-agent-effects] handler failed');+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'metrics-agent-effects',+ cause: e,+ });+ }+ }+async function handleEmbedDetect(req: IncomingMessage, res: ServerResponse): Promise<void> {// Diagnostic endpoint for the Cursor / Codex / Claude Code embedded-viewer// detection spikes. Reads from the in-process ring buffer populated in@@ -17707,6 +17795,21 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {async (_req, res, body) => {try {const logger = getLogger('renderer');+ if (body.droppedSinceLastFlush !== undefined && body.droppedSinceLastFlush > 0) {+ // Gap marker: the forwarder lost entries (buffer overflow / failed+ // POSTs) between the previous delivered batch and this one. Persist+ // it as its own line so a log reader knows the silence was loss,+ // not inactivity.+ logger.warn(+ {+ source: 'renderer-console',+ transport: 'web',+ event: 'client-log-entries-dropped',+ droppedSinceLastFlush: body.droppedSinceLastFlush,+ },+ 'client-log-entries-dropped',+ );+ }for (const entry of body.entries) {// Per-entry guard: one entry that trips a pino serialization fault// must not drop the rest of the batch (the response still reports the@@ -18633,6 +18736,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {'/api/metrics/reconciliation': handleMetricsReconciliation,'/api/metrics/parse-health': handleMetricsParseHealth,'/api/metrics/agent-presence': handleMetricsAgentPresence,+ '/api/metrics/agent-effects': handleMetricsAgentEffects,'/api/__embed-detect': handleEmbedDetect,'/api/server-info': handleServerInfo,'/api/share/construct-url': handleShareConstructUrl,diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.tsindex 85e2bb9be..d7081b90c 100644--- a/packages/server/src/server-observers.ts+++ b/packages/server/src/server-observers.ts@@ -60,6 +60,7 @@ import {} from './bridge-watchdog.ts';import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';+import { getLogger } from './logger.ts';import { computeMapDrivenBodySplice } from './map-driven-splice.ts';import {incrementBridgeMergeCheckpointCreated,@@ -81,6 +82,14 @@ import {import { type ShadowHandle, saveInMemoryCheckpoint } from './shadow-repo.ts';import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';+/**+ * Pino line for checkpoint-write failures, alongside the existing+ * console.warn: a failed checkpoint means the recovery snapshot for a+ * detected content-loss event was NOT persisted, and the pino sink is what+ * reaches the local log files (and, through them, diagnostics bundles).+ */+const checkpointLog = getLogger('server-observers');+// ─────────────────────────────────────────────────────────────// Origin constant// ─────────────────────────────────────────────────────────────@@ -675,6 +684,10 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidmessage: err.message,stack: err.stack?.split('\n').slice(0, 4).join('\n'),});+ checkpointLog.warn(+ { err, 'doc.name': opts.docName ?? null, branch, kind: 'bridge-merge-loss' },+ 'checkpoint write failed',+ );});});};@@ -759,6 +772,10 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidmessage: e.message,stack: e.stack?.split('\n').slice(0, 4).join('\n'),});+ checkpointLog.warn(+ { err: e, 'doc.name': docName, branch, kind: 'observer-a-duplication' },+ 'checkpoint write failed',+ );});});};@@ -1100,6 +1117,10 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidmessage: e.message,stack: e.stack?.split('\n').slice(0, 4).join('\n'),});+ checkpointLog.warn(+ { err: e, 'doc.name': docName, branch, kind: 'producer-guard-loss' },+ 'checkpoint write failed',+ );});});};