Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): watcher decision ring + lifecycle breadcrumbs (#2803)

Andrew Mikofalvy57984d2d5f21
diff --git a/.changeset/watcher-ring-lifecycle-breadcrumbs.md b/.changeset/watcher-ring-lifecycle-breadcrumbs.md
new file mode 100644
index 000000000..1a4d48264
--- /dev/null
+++ b/.changeset/watcher-ring-lifecycle-breadcrumbs.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Bug-report bundles now capture watcher decisions and lifecycle breadcrumbs. The file watcher keeps a bounded in-memory ring of its last 256 decisions — dispatched events, self-write skips, and drops with a bounded reason (symlink escape, filter exclusion, unreadable/raced file, reserved doc, stat failure) — served by a new loopback-only `GET /api/metrics/watcher-recent` endpoint and staged into the full diagnose bundle as `state/watcher-recent.jsonl` (one decision per line, paths pre-normalized; doc names anonymized by the existing `--redact` pass). Drops also increment an `ok.file_watcher.drops` counter and roll up into a periodic drop-count summary log line, so "my file didn't sync" is diagnosable from a bundle. Near-silent critical subsystems gained debug-level lifecycle breadcrumbs keyed on doc/agent/session: agent-session create/join/close/undo/write transitions, bridge-watchdog tolerance/path-B/split-brain firings plus a content-free diff summary (lengths and first-divergence offset, never document bytes) on every emitted invariant violation, and the client provider pool's reconnect/recycle path (recycle timers, mismatch buffer capture, IDB clears, replay fallbacks) via structured console breadcrumbs the log forwarder ships to the server log. The pino file sink now admits debug records by default (`OK_FILE_LEVEL` overrides; terminals keep the base level) so bundles capture the breadcrumbs without extra terminal noise.
diff --git a/knip.config.ts b/knip.config.ts
index d8a79af2f..6f8bbbc63 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -122,9 +122,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/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.ts
index 0be84b339..c3475f07f 100644
--- a/packages/app/src/editor/provider-pool.ts
+++ b/packages/app/src/editor/provider-pool.ts
@@ -1244,6 +1244,17 @@ export class ProviderPool {
console.warn(JSON.stringify(parts));
}
+ /**
+ * Info-level lifecycle breadcrumb for the reconnect/recycle path. Same
+ * structured-console channel as the recovery events (the client log
+ * forwarder lifts `{event, ...fields}` JSON into the server log, so these
+ * reach diagnostics bundles), but at `console.info` — breadcrumbs are
+ * expected transitions, not warnings.
+ */
+ private emitStructuredClientBreadcrumb(parts: Record<string, string | number | boolean>): void {
+ console.info(JSON.stringify(parts));
+ }
+
private clearRecoveryMismatchStaleClaimIfTerminal(): void {
const kind = this.serverRestartRecoveryState.kind;
if (kind === 'idle' || kind === 'failed') {
@@ -1252,6 +1263,11 @@ export class ProviderPool {
}
private beginServerRestartRecovery(docNames: readonly string[], startedAt: number): void {
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-restart-recovery-begin',
+ phase: 'clearing-local-cache',
+ docCount: docNames.length,
+ });
this.serverRestartRecoveryState = {
kind: 'recovering',
phase: 'clearing-local-cache',
@@ -1271,6 +1287,11 @@ export class ProviderPool {
startedAt: number,
failureReason: 'clear-data-failed' | 'clear-data-timeout',
): void {
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-restart-recovery-reconnecting',
+ docCount: docNames.length,
+ failedCount: failedDocNames.length,
+ });
if (docNames.length === 0) {
this.serverRestartRecoveryState =
failedDocNames.length === 0
@@ -1304,6 +1325,11 @@ export class ProviderPool {
if (!state.docNames.includes(docName)) return;
const remaining = state.docNames.filter((candidate) => candidate !== docName);
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-restart-recovery-synced',
+ docName,
+ remaining: remaining.length,
+ });
if (remaining.length > 0) {
this.serverRestartRecoveryState = { ...state, docNames: remaining };
return;
@@ -1778,6 +1804,11 @@ export class ProviderPool {
// are no-ops — they shouldn't extend the window because each one just
// means "still can't reach the server."
if (entry.hasSynced && provider.unsyncedChanges === 0 && !entry.pendingRecycleTimer) {
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-recycle-timer-armed',
+ docName,
+ debounceMs: this.recycleDebounceMs,
+ });
entry.pendingRecycleTimer = setTimeout(() => {
// Re-narrow inside the timer closure — `entry` was Active when the
// timer was scheduled, but TS doesn't carry the narrowing across
@@ -1799,6 +1830,10 @@ export class ProviderPool {
// timer so resource reclamation still happens.
if (provider.unsyncedChanges > 0) {
mark('ok/pool/recycle-skipped-unsynced', { docName });
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-recycle-skipped-unsynced',
+ docName,
+ });
return;
}
this.recycleDisconnectedEntry(docName);
@@ -2075,6 +2110,11 @@ export class ProviderPool {
// — kept as the terminal fallback so this path never REGRESSES
// relative to the pre-content-replay behavior.
Y.applyUpdate(provider.document, current.delta, TAB_REPLAY_ORIGIN);
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-buffer-replay-delta-applied',
+ docName,
+ deltaBytes: current.delta.byteLength,
+ });
} catch (err: unknown) {
const errorName = err instanceof Error ? err.name : 'non-error-throw';
this.emitStructuredClientRecoveryEvent({
@@ -2202,6 +2242,11 @@ export class ProviderPool {
// Snapshot entries BEFORE any async work — subsequent recycle mutates
// the map via destroyEntry → delete → re-open.
const snapshot = Array.from(this.entries.entries());
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-mismatch-recycle-begin',
+ entryCount: snapshot.length,
+ branch: this.normalizedObservedBranch(),
+ });
const startedAt = Date.now();
const recoveryActiveDocName = this.activeDocName;
// Recovery UI (spinner + failure panel) only tracks the foreground doc.
@@ -2275,6 +2320,12 @@ export class ProviderPool {
delta: unsynced,
fullState: fullState.byteLength > MAX_BUFFER_BYTES ? null : fullState,
});
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-mismatch-buffer-captured',
+ docName,
+ deltaBytes: unsynced.byteLength,
+ fullStateBytes: fullState.byteLength > MAX_BUFFER_BYTES ? 0 : fullState.byteLength,
+ });
}
}
@@ -2302,6 +2353,10 @@ export class ProviderPool {
promise: this.withClearDataTimeout(docName, poolEntry.persistence.clearData()),
});
}
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-mismatch-clears-begin',
+ count: clears.length,
+ });
const inflight: Promise<void> = Promise.allSettled(clears.map((c) => c.promise))
.then((results) => {
@@ -2499,6 +2554,10 @@ export class ProviderPool {
*/
recycleAllEntries(): void {
const docNames = Array.from(this.entries.keys());
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-recycle-all',
+ count: docNames.length,
+ });
for (const docName of docNames) {
this.recycleDisconnectedEntry(docName);
}
@@ -2993,6 +3052,11 @@ export class ProviderPool {
const wasActive = this.activeDocName === docName;
mark('ok/pool/recycle-disconnected', { docName, wasActive });
+ this.emitStructuredClientBreadcrumb({
+ event: 'ok-pool-recycle-entry',
+ docName,
+ wasActive,
+ });
this.destroyEntry(entry);
this._entries.delete(docName);
diff --git a/packages/app/tests/integration/api-error-envelope/metrics-watcher-recent.test.ts b/packages/app/tests/integration/api-error-envelope/metrics-watcher-recent.test.ts
new file mode 100644
index 000000000..7605f2ecc
--- /dev/null
+++ b/packages/app/tests/integration/api-error-envelope/metrics-watcher-recent.test.ts
@@ -0,0 +1,87 @@
+/**
+ * Per-handler narrow-integration smoke test for `handleMetricsWatcherRecent`.
+ *
+ * Asserts the canonical RFC 9457 wire shape for
+ * `GET /api/metrics/watcher-recent`. Shares the same
+ * auth-before-method-dispatch ordering as `handleMetricsAgentEffects`
+ * (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
+ * `MetricsWatcherRecentSuccessSchema`, no `ok` discriminator; every
+ * entry's `doc.name` is a normalized path (never absolute).
+ * - 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 {
+ MetricsWatcherRecentSuccessSchema,
+ ProblemDetailsSchema,
+} from '@inkeep/open-knowledge-core';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+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-watcher-recent envelope (RFC 9457)', () => {
+ test('happy path emits flat success body with application/json and normalized paths', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/watcher-recent`);
+ expect(res.status).toBe(200);
+ expect(res.headers.get('content-type')).toBe('application/json');
+
+ const body = await res.json();
+ const parsed = MetricsWatcherRecentSuccessSchema.safeParse(body);
+ expect(parsed.success).toBe(true);
+ expect((body as Record<string, unknown>).ok).toBeUndefined();
+ if (!parsed.success) return;
+ // Paths are pre-normalized at record time — an absolute path in the wire
+ // body would be a cardinality/privacy regression.
+ for (const decision of parsed.data.decisions) {
+ expect(decision['doc.name'].startsWith('/')).toBe(false);
+ }
+ });
+
+ 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/watcher-recent`,
+ '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/watcher-recent`, {
+ 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.ts
index 7d1cf2681..b7230e229 100644
--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts
+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
@@ -198,6 +198,10 @@ const EXEMPT_HANDLERS = new Set([
// (per-doc agent-effects ring-buffer summaries). Read path, no writes,
// nothing to attribute — same posture as `handleMetricsAgentPresence`.
'handleMetricsAgentEffects',
+ // `/api/metrics/watcher-recent` — GET-only loopback + host-gated diagnostic
+ // (file-watcher recent-decisions ring). Read path, no writes, nothing to
+ // attribute — same posture as `handleMetricsAgentEffects`.
+ 'handleMetricsWatcherRecent',
// `/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/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.ts
index 062ae6f46..1fad3d63e 100644
--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts
+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts
@@ -135,6 +135,11 @@ const EXEMPT_HANDLERS = new Set([
// targets no Y.Doc write, so the per-doc conflict gate does not apply — same
// posture as its `handleMetricsAgentPresence` sibling.
'handleMetricsAgentEffects',
+ // `/api/metrics/watcher-recent` — GET-only loopback + host-gated diagnostic
+ // returning the file-watcher's recent-decisions ring. Reads only; targets no
+ // Y.Doc write, so the per-doc conflict gate does not apply — same posture as
+ // its `handleMetricsAgentEffects` sibling.
+ 'handleMetricsWatcherRecent',
// `/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 gate
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index 1a6ae2626..9ff5063d9 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -1202,7 +1202,8 @@ function parseUiPort(value: string): number {
* should stay legible — banner + warnings, not a firehose of INFO diagnostics
* — but those diagnostics must still reach the on-disk file sink for
* bug-report bundles. Returning 'warn' raises ONLY the pretty stdout stream
- * (see `OK_CONSOLE_LEVEL` in `logger.ts`); the file sink keeps the base level.
+ * (see `OK_CONSOLE_LEVEL` in `logger.ts`); the file sink keeps capturing
+ * diagnostics independently (debug+ by default; `OK_FILE_LEVEL` overrides).
*
* Returns `null` (leave the env untouched) when the user has already pinned a
* level explicitly via `OK_CONSOLE_LEVEL` or `LOG_LEVEL` — the discoverable
diff --git a/packages/cli/src/diagnose/bundle-redact.test.ts b/packages/cli/src/diagnose/bundle-redact.test.ts
index 2fe6333b7..83602682a 100644
--- a/packages/cli/src/diagnose/bundle-redact.test.ts
+++ b/packages/cli/src/diagnose/bundle-redact.test.ts
@@ -12,10 +12,10 @@
* and assert on the rewritten files + the returned map.
*/
-import { afterEach, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
+import { afterEach, describe, expect, test } from 'vitest';
import {
_recordHashForTests,
type RedactStagedBundleResult,
@@ -430,6 +430,42 @@ describe('redactStagedBundle — contentDir substitution', () => {
expect(Object.values(result.docNameMap)).toContain('meetings/standup');
});
+ test('hashes doc.name values in state/watcher-recent.jsonl via the line-wise walker', () => {
+ const stagingDir = makeStagingDir();
+ const contentDir = '/Users/test/notes';
+ const lines = [
+ JSON.stringify({
+ ts: 1,
+ decision: 'dispatched',
+ kind: 'create',
+ 'doc.name': '.../meetings/standup.md',
+ pathRole: 'content-md',
+ }),
+ JSON.stringify({
+ ts: 2,
+ decision: 'drop-filter-excluded',
+ kind: 'update',
+ 'doc.name': '.../dist/output.md',
+ pathRole: 'content-md',
+ }),
+ ];
+ writeStaged(stagingDir, 'state/watcher-recent.jsonl', `${lines.join('\n')}\n`);
+
+ const result = redactStagedBundle({ stagingDir, contentDir });
+
+ const after = readStaged(stagingDir, 'state/watcher-recent.jsonl');
+ expect(after).not.toContain('standup');
+ expect(after).not.toContain('output.md');
+ const parsed = after
+ .trim()
+ .split('\n')
+ .map((line) => JSON.parse(line));
+ expect(parsed[0]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
+ expect(parsed[0].decision).toBe('dispatched');
+ expect(parsed[1]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
+ expect(Object.values(result.docNameMap)).toContain('.../meetings/standup.md');
+ });
+
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.ts
index 79e95bdc7..d5ebf0003 100644
--- a/packages/cli/src/diagnose/bundle-redact.ts
+++ b/packages/cli/src/diagnose/bundle-redact.ts
@@ -301,7 +301,12 @@ export function redactStagedBundle(opts: RedactStagedBundleOpts): RedactStagedBu
// misses the STATE_JSON_FILES set and silently falls through to the
// substring-only walker.
const base = basename(filePath);
- if (STATE_JSON_FILES.has(base)) {
+ if (filePath.endsWith('.jsonl')) {
+ // JSONL state artifacts (watcher-recent.jsonl) carry per-line
+ // `doc.name` keys; the line-wise walker hashes them like the
+ // telemetry/log JSONLs.
+ redactJsonlFile(filePath, ctx);
+ } else if (STATE_JSON_FILES.has(base)) {
redactJsonFile(filePath, ctx);
} else {
redactPlainFile(filePath, ctx);
diff --git a/packages/cli/src/diagnose/bundle.test.ts b/packages/cli/src/diagnose/bundle.test.ts
index fdc370fae..9b03d7d2e 100644
--- a/packages/cli/src/diagnose/bundle.test.ts
+++ b/packages/cli/src/diagnose/bundle.test.ts
@@ -6,7 +6,6 @@
* `CollectBundleDeps` so tests stay deterministic and hermetic.
*/
-import { afterEach, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import {
existsSync,
@@ -19,6 +18,7 @@ import {
} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
+import { afterEach, describe, expect, test } from 'vitest';
import { ZipFile } from 'yazl';
import { type CollectBundleDeps, collectBundle, writeBundle } from './bundle.ts';
@@ -45,6 +45,7 @@ function makeDeterministicDeps(over: Partial<CollectBundleDeps> = {}): CollectBu
return {
fetchAgentPresence: async () => null,
fetchAgentEffects: async () => null,
+ fetchWatcherRecent: async () => null,
readShadowHead: () => null,
readCheckpointRefs: () => null,
now: () => new Date('2026-05-28T14:22:01.000Z'),
@@ -336,6 +337,98 @@ describe('collectBundle — server status', () => {
collected.cleanup();
});
+ test('lock present + watcher-recent 2xx → watcher-recent.jsonl staged as one line per decision', 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 decisions = [
+ {
+ ts: 1,
+ decision: 'dispatched',
+ kind: 'create',
+ 'doc.name': '.../notes/a.md',
+ pathRole: 'content-md',
+ },
+ {
+ ts: 2,
+ decision: 'drop-symlink-escape',
+ kind: 'update',
+ 'doc.name': '.../x/b.md',
+ pathRole: 'content-md',
+ },
+ ];
+ const deps = makeDeterministicDeps({
+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),
+ fetchWatcherRecent: async (port) => {
+ queriedPort = port;
+ return JSON.stringify({ decisions });
+ },
+ });
+ const collected = await collectBundle({ contentDir, deps });
+
+ expect(queriedPort).toBe(4711);
+ const watcherPath = join(collected.stagingDir, 'state', 'watcher-recent.jsonl');
+ expect(existsSync(watcherPath)).toBe(true);
+ const lines = readFileSync(watcherPath, 'utf-8').trim().split('\n');
+ expect(lines).toHaveLength(2);
+ expect(JSON.parse(lines[0] ?? '')).toEqual(decisions[0]);
+ expect(JSON.parse(lines[1] ?? '')).toEqual(decisions[1]);
+ // JSONL files are line-counted in the manifest inventory.
+ const entry = collected.manifest.files.find((f) => f.path === 'state/watcher-recent.jsonl');
+ expect(entry?.lines).toBe(2);
+ collected.cleanup();
+ });
+
+ test('watcher-recent empty ring stages an empty file; malformed body is skipped', async () => {
+ const contentDir = makeTmpDir();
+ writeAt(
+ contentDir,
+ '.ok/local/server.lock',
+ JSON.stringify({ pid: 1, port: 4711, hostname: 'h', startedAt: 't', worktreeRoot: '/' }),
+ );
+ const emptyDeps = makeDeterministicDeps({
+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),
+ fetchWatcherRecent: async () => JSON.stringify({ decisions: [] }),
+ });
+ const emptyCollected = await collectBundle({ contentDir, deps: emptyDeps });
+ const watcherPath = join(emptyCollected.stagingDir, 'state', 'watcher-recent.jsonl');
+ expect(existsSync(watcherPath)).toBe(true);
+ expect(readFileSync(watcherPath, 'utf-8')).toBe('');
+ emptyCollected.cleanup();
+
+ const malformedDeps = makeDeterministicDeps({
+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),
+ fetchWatcherRecent: async () => 'not json {',
+ });
+ const malformedCollected = await collectBundle({ contentDir, deps: malformedDeps });
+ expect(existsSync(join(malformedCollected.stagingDir, 'state', 'watcher-recent.jsonl'))).toBe(
+ false,
+ );
+ malformedCollected.cleanup();
+ });
+
+ test('watcher-recent 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: {} }),
+ fetchWatcherRecent: async () => null,
+ });
+ const collected = await collectBundle({ contentDir, deps });
+
+ expect(collected.manifest.serverStatus).toBe('running');
+ expect(existsSync(join(collected.stagingDir, 'state', 'watcher-recent.jsonl'))).toBe(false);
+ collected.cleanup();
+ });
+
test('agent-effects failure never affects serverStatus (presence is the probe)', async () => {
const contentDir = makeTmpDir();
writeAt(
diff --git a/packages/cli/src/diagnose/bundle.ts b/packages/cli/src/diagnose/bundle.ts
index 971bdc454..b59231d87 100644
--- a/packages/cli/src/diagnose/bundle.ts
+++ b/packages/cli/src/diagnose/bundle.ts
@@ -209,6 +209,13 @@ export interface CollectBundleDeps {
* Best-effort like agent-presence; a `null` never affects `serverStatus`.
*/
fetchAgentEffects?: (port: number) => Promise<string | null>;
+ /**
+ * Fetch the running server's `GET /api/metrics/watcher-recent` response
+ * (the file-watcher's bounded recent-decisions ring), within the 1s
+ * budget. Returns the response body string on 2xx, or `null` on any
+ * failure. Best-effort like agent-effects; never affects `serverStatus`.
+ */
+ fetchWatcherRecent?: (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
@@ -370,6 +377,42 @@ async function defaultFetchAgentEffects(port: number): Promise<string | null> {
}
}
+async function defaultFetchWatcherRecent(port: number): Promise<string | null> {
+ try {
+ const response = await fetch(`http://127.0.0.1:${port}/api/metrics/watcher-recent`, {
+ 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-effects.
+ return null;
+ }
+}
+
+/**
+ * Convert the watcher-recent JSON response (`{decisions: [...]}`) into JSONL
+ * (one decision per line) for staging as `state/watcher-recent.jsonl`. JSONL
+ * keeps the artifact greppable and routes it through the same line-wise
+ * redaction pass the telemetry/log JSONLs get. Returns `null` when the body
+ * doesn't parse to the expected shape (older server, torn response) — the
+ * artifact is then skipped, mirroring the other best-effort fetches. An
+ * empty ring stages an empty file so "endpoint reachable, ring empty" stays
+ * distinguishable from "not captured".
+ */
+function watcherRecentToJsonl(body: string): string | null {
+ try {
+ const parsed: unknown = JSON.parse(body);
+ if (typeof parsed !== 'object' || parsed === null) return null;
+ const decisions = (parsed as { decisions?: unknown }).decisions;
+ if (!Array.isArray(decisions)) return null;
+ if (decisions.length === 0) return '';
+ return `${decisions.map((decision) => JSON.stringify(decision)).join('\n')}\n`;
+ } catch {
+ return null;
+ }
+}
+
function defaultReadShadowHead(contentDir: string): string | null {
const shadowDir = join(contentDir, '.git', 'ok');
if (!existsSync(shadowDir)) return null;
@@ -627,6 +670,7 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
const deps = opts.deps ?? {};
const fetchAgentPresence = deps.fetchAgentPresence ?? defaultFetchAgentPresence;
const fetchAgentEffects = deps.fetchAgentEffects ?? defaultFetchAgentEffects;
+ const fetchWatcherRecent = deps.fetchWatcherRecent ?? defaultFetchWatcherRecent;
const readShadowHead = deps.readShadowHead ?? defaultReadShadowHead;
const readCheckpointRefs = deps.readCheckpointRefs ?? defaultReadCheckpointRefs;
const now = deps.now ?? (() => new Date());
@@ -687,6 +731,16 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
if (agentEffects !== null) {
writeFileSync(join(stagingDir, 'state', 'agent-effects.json'), agentEffects);
}
+ // File-watcher recent-decisions ring — the "my file didn't sync"
+ // triage artifact (which events were dispatched / skipped / dropped,
+ // and why). Best effort like agent-effects; staged as JSONL.
+ const watcherRecent = await fetchWatcherRecent(lockPort);
+ if (watcherRecent !== null) {
+ const jsonl = watcherRecentToJsonl(watcherRecent);
+ if (jsonl !== null) {
+ writeFileSync(join(stagingDir, 'state', 'watcher-recent.jsonl'), jsonl);
+ }
+ }
}
// Shadow-repo head — best effort.
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: string
return 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.ts
index 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.ts
index 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.ts
index 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.ts
index 3681841fb..5d72bbe86 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -757,6 +757,8 @@ export {
MetricsParseHealthSuccessSchema,
type MetricsReconciliationSuccess,
MetricsReconciliationSuccessSchema,
+ type MetricsWatcherRecentSuccess,
+ MetricsWatcherRecentSuccessSchema,
type OrphanEntry,
OrphanEntrySchema,
type OrphanHint,
@@ -1011,6 +1013,8 @@ export {
UploadAssetSuccessSchema,
type UploadRequest,
UploadRequestSchema,
+ WatcherDecisionEntrySchema,
+ type WatcherDecisionEntryWire,
type WorkspaceSuccess,
WorkspaceSuccessSchema,
type WriteWarning,
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 8dc3a81b5..b1f252c31 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 { List, Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -86,8 +85,7 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw 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.ts
index 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.ts
index 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?: StructuralFreshnessChec
return 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-files.ts b/packages/core/src/markdown/lint/config-files.ts
index 94b34dee1..312c9c74b 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,4 +1,3 @@
-
const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set([
'.markdownlint.json',
'.markdownlint.jsonc',
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 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.ts
index 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, MarkdownlintRuleSetting
MD013: 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.ts
index d763d8d28..8a154ce30 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/metrics.ts b/packages/core/src/schemas/api/metrics.ts
index c9076e4ea..aebfedf1c 100644
--- a/packages/core/src/schemas/api/metrics.ts
+++ b/packages/core/src/schemas/api/metrics.ts
@@ -212,6 +212,41 @@ export const MetricsAgentEffectsSuccessSchema = z
.loose() satisfies StandardSchemaV1;
export type MetricsAgentEffectsSuccess = z.infer<typeof MetricsAgentEffectsSuccessSchema>;
+/**
+ * One file-watcher decision entry on
+ * `MetricsWatcherRecentSuccessSchema.decisions`. The path is pre-normalized
+ * server-side (last two segments) and carried 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 without a redactor change.
+ *
+ * `decision` / `kind` are permissive strings (operator-read fields; pinning
+ * the enum here would force lockstep maintenance with the server's decision
+ * taxonomy without catching real regressions).
+ */
+export const WatcherDecisionEntrySchema = z
+ .object({
+ ts: z.number().int().min(0),
+ decision: z.string().min(1),
+ kind: z.string().min(1),
+ 'doc.name': z.string().min(1),
+ pathRole: z.string().min(1),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type WatcherDecisionEntryWire = z.infer<typeof WatcherDecisionEntrySchema>;
+
+/**
+ * Success response for `GET /api/metrics/watcher-recent`. Returns the
+ * bounded ring of recent file-watcher decisions (dispatched / self-write
+ * skips / drops), oldest first. Loopback + Host-allowlist gated like
+ * `/api/metrics/agent-effects`.
+ */
+export const MetricsWatcherRecentSuccessSchema = z
+ .object({
+ decisions: z.array(WatcherDecisionEntrySchema),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type MetricsWatcherRecentSuccess = z.infer<typeof MetricsWatcherRecentSuccessSchema>;
+
/**
* Success response for `GET /api/installed-agents`. Returns a flat boolean
* record keyed by agent scheme name (`claude` / `codex` / `cursor`). The
diff --git a/packages/server/src/agent-sessions.ts b/packages/server/src/agent-sessions.ts
index 6627a8b03..ba6c9e9a0 100644
--- a/packages/server/src/agent-sessions.ts
+++ b/packages/server/src/agent-sessions.ts
@@ -360,7 +360,17 @@ function applyAgentMarkdownWriteInner(
// the warning's `currentState` so the agent recovers without a re-read.
// Post-transact concurrent-peer residue is out of scope here.
const actualYText = document.getText('source').toString();
- return evaluateContentDivergence(actualYText, newContent, position);
+ const divergence = evaluateContentDivergence(actualYText, newContent, position);
+ log.debug(
+ {
+ docName: document.name,
+ position,
+ markdownBytes: markdown.length,
+ divergent: divergence !== undefined,
+ },
+ '[agent-write] applied agent markdown write',
+ );
+ return divergence;
} catch (err) {
// `FrontmatterMalformedError` is the designed-rejection path: it carries
// a 400 envelope to the agent and `respondFrontmatterMalformed` already
@@ -512,6 +522,10 @@ function applyAgentUndoInner(
if (undone) deriveFragmentFromYtext(document, embedResolver);
}, undoOrigin);
+ log.debug(
+ { docName: session.docName, agentId: session.agentId, scope, framesToPop, undone },
+ '[agent-session] applied agent undo',
+ );
return undone;
}
@@ -729,13 +743,20 @@ export class AgentSessionManager {
// Reuse in-flight promise if a concurrent first-call is already pending
const inflight = this.pendingSessions.get(key);
- if (inflight) return inflight;
+ if (inflight) {
+ log.debug({ docName, agentId }, '[agent-session] joining in-flight session creation');
+ return inflight;
+ }
// Capacity gate — fires only when creating a NEW (docName, agentId)
// entry. Existing-session lookups returned above. Counts both resolved
// and pending so a concurrent burst of distinct ids cannot race past
// the cap before any of them lands in `sessions`.
if (this.sessions.size + this.pendingSessions.size >= this.maxSessions) {
+ log.warn(
+ { docName, agentId, limit: this.maxSessions },
+ '[agent-session] session capacity reached, refusing new session',
+ );
throw new AgentSessionCapacityError(this.maxSessions);
}
@@ -789,6 +810,10 @@ export class AgentSessionManager {
docName,
sessionContext,
)) as AgentDirectConnection;
+ log.debug(
+ { docName, agentId, sessionId: rawSessionId, agentType },
+ '[agent-session] DirectConnection opened',
+ );
// NO per-doc awareness writes here. Every Hocuspocus `Document` has a
// single shared `Awareness` clientID borrowed from `doc.clientID`, so a per-
@@ -836,7 +861,10 @@ export class AgentSessionManager {
um.on('stack-item-added', stampTime);
um.on('stack-item-updated', stampTime);
- log.info({ docName, agentId }, `[agent-session] Created session for: ${docName} / ${agentId}`);
+ log.info(
+ { docName, agentId, sessionId: rawSessionId },
+ `[agent-session] Created session for: ${docName} / ${agentId}`,
+ );
return { dc, origin, undoOrigin, um, agentId, docName };
}
@@ -867,6 +895,10 @@ export class AgentSessionManager {
session: SessionRecord,
context: Record<string, unknown>,
): Promise<void> {
+ log.debug(
+ { docName: session.docName, agentId: session.agentId, ...context },
+ '[agent-session] closing session',
+ );
try {
try {
session.um.destroy();
@@ -923,6 +955,10 @@ export class AgentSessionManager {
// Collect matching keys first — the async disconnect + delete below mutates
// `this.sessions`, so iterating directly would hit concurrent-modification.
const keys = [...this.sessions.keys()].filter((k) => k.endsWith(suffix));
+ log.debug(
+ { agentId, pendingSettled: pendingKeys.length, closing: keys.length },
+ '[agent-session] closing all sessions for agent',
+ );
for (const key of keys) {
const session = this.sessions.get(key);
if (!session) continue;
@@ -936,6 +972,7 @@ export class AgentSessionManager {
// Collect matching keys first — the async disconnect + delete below mutates
// `this.sessions`, so iterating directly would hit concurrent-modification.
const keys = [...this.sessions.keys()].filter((k) => k.startsWith(prefix));
+ log.debug({ docName, closing: keys.length }, '[agent-session] closing all sessions for doc');
for (const key of keys) {
const session = this.sessions.get(key);
if (!session) continue;
@@ -950,6 +987,7 @@ export class AgentSessionManager {
return;
}
const keys = [...this.sessions.keys()];
+ log.debug({ closing: keys.length }, '[agent-session] closing all sessions');
for (const key of keys) {
const session = this.sessions.get(key);
if (!session) continue;
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index b5aa00051..ee3fe2ed4 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -136,6 +136,8 @@ import {
MetricsAgentPresenceSuccessSchema,
MetricsParseHealthSuccessSchema,
MetricsReconciliationSuccessSchema,
+ type MetricsWatcherRecentSuccess,
+ MetricsWatcherRecentSuccessSchema,
mediaKindForSidebarAssetExtension,
normalizeAttachmentFolderPath,
OK_DIR,
@@ -488,6 +490,7 @@ import {
type DiskEvent,
type FileIndexEntry,
type FolderIndexEntry,
+ getWatcherDecisionRingSnapshot,
registerWrite,
removeFolderIndexEntries as removeFolderIndexEntriesFromIndex,
updateFileIndex,
@@ -9100,6 +9103,64 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
}
}
+ async function handleMetricsWatcherRecent(
+ req: IncomingMessage,
+ res: ServerResponse,
+ ): Promise<void> {
+ // Diagnostic view of the file-watcher's recent-decisions ring — the
+ // record of which disk events were dispatched, skipped as self-writes,
+ // or dropped (and why), which otherwise lives only in server memory.
+ // Loopback + Host-header gated with auth-before-method-dispatch ordering
+ // — same pattern + rationale as `handleMetricsAgentEffects` (which files
+ // changed on this machine, and when, is a local-editing-only signal).
+ if (!isLoopbackAddress(req.socket.remoteAddress)) {
+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
+ handler: 'metrics-watcher-recent',
+ });
+ return;
+ }
+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {
+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler: 'metrics-watcher-recent',
+ });
+ return;
+ }
+ if (req.method !== 'GET') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'metrics-watcher-recent',
+ extraHeaders: { Allow: 'GET' },
+ });
+ return;
+ }
+ try {
+ // Ring paths are already normalized (last two segments) at record
+ // time. The wire carries them 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.
+ const decisions: MetricsWatcherRecentSuccess['decisions'] =
+ getWatcherDecisionRingSnapshot().map((record) => ({
+ ts: record.ts,
+ decision: record.decision,
+ kind: record.kind,
+ 'doc.name': record.path,
+ pathRole: record.pathRole,
+ }));
+ successResponse(
+ res,
+ 200,
+ MetricsWatcherRecentSuccessSchema,
+ { decisions },
+ { handler: 'metrics-watcher-recent' },
+ );
+ } catch (e) {
+ log.error({ err: e }, '[metrics-watcher-recent] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'metrics-watcher-recent',
+ 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
@@ -19036,6 +19097,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
'/api/metrics/parse-health': handleMetricsParseHealth,
'/api/metrics/agent-presence': handleMetricsAgentPresence,
'/api/metrics/agent-effects': handleMetricsAgentEffects,
+ '/api/metrics/watcher-recent': handleMetricsWatcherRecent,
'/api/__embed-detect': handleEmbedDetect,
'/api/server-info': handleServerInfo,
'/api/acp/catalog': handleAcpCatalog,
diff --git a/packages/server/src/bridge-watchdog.ts b/packages/server/src/bridge-watchdog.ts
index 210eb48ba..9f9e48519 100644
--- a/packages/server/src/bridge-watchdog.ts
+++ b/packages/server/src/bridge-watchdog.ts
@@ -53,6 +53,7 @@ import {
PARSE_EQUIVALENCE_TOLERANCE,
toBridgeInvariantLog,
} from '@inkeep/open-knowledge-core';
+import { getLogger } from './logger.ts';
import {
incrementBridgeInvariantViolations,
incrementBridgeInvariantViolationsSuppressed,
@@ -61,6 +62,13 @@ import {
incrementObserverAPathBFiresSuppressed,
} from './metrics.ts';
+// Pino lifecycle breadcrumbs ride alongside the structured console events:
+// the console channel is an observation contract for in-process test
+// harnesses (terminal-only), while the pino file sink is what bug-report
+// bundles collect — without these, the watchdog's firings are invisible in
+// a bundle.
+const log = getLogger('bridge-watchdog');
+
// ─────────────────────────────────────────────────────────────
// Rate-limiter
// ─────────────────────────────────────────────────────────────
@@ -307,6 +315,16 @@ export function emitObserverAPathBFired(docName: string | undefined, nowMs?: num
const shouldEmit = shouldEmitObserverAPathBFired(docName, nowMs);
if (!shouldEmit) {
incrementObserverAPathBFiresSuppressed();
+ } else {
+ // Behind the debounce gate on purpose: Path B can fire per keystroke
+ // under concurrent editing, and un-gated per-fire logging inside the
+ // drain measurably widens the witness-to-settle race window the canary
+ // e2e suite guards (raising its failure rate in CI). The suppressed
+ // counter accounts for the gap.
+ log.debug(
+ { docName },
+ '[bridge-watchdog] Observer A Path B fired (slow-path Y.Text divergence merge)',
+ );
}
return shouldEmit;
}
@@ -358,6 +376,11 @@ export function emitBridgeSplitBrainRederive(
const shouldEmit = shouldEmitBridgeSplitBrainRederive(site, docName, nowMs);
if (!shouldEmit) {
incrementBridgeSplitBrainRederivesSuppressed();
+ } else {
+ // Behind the debounce gate — same per-drain hot-path rationale as
+ // `emitObserverAPathBFired` (the split-brain check runs per Observer A
+ // drain on an irreducibly-divergent doc).
+ log.debug({ site, docName }, '[bridge-watchdog] split-brain re-derive detected');
}
return shouldEmit;
}
@@ -461,6 +484,14 @@ export function createDocCanonicalizer(
// Watchdog assertion
// ─────────────────────────────────────────────────────────────
+/** Offset of the first differing character (== min length when one input is a prefix of the other). */
+function firstDivergenceIndex(a: string, b: string): number {
+ const max = Math.min(a.length, b.length);
+ let i = 0;
+ while (i < max && a[i] === b[i]) i++;
+ return i;
+}
+
interface AssertBridgeInvariantOpts {
site: BridgeInvariantSite;
/** Doc name for log attribution + rate-limiter scoping. */
@@ -556,6 +587,16 @@ export function assertBridgeInvariant(
if (classes.length > 0) {
emitToleranceFire(classes, ytextSnapshot, fragmentMdSnapshot, opts.docName);
}
+ // Breadcrumb rides the SAME (site, class) debounce as the console event
+ // — the tolerance path runs on every drain of a canonicalizing doc
+ // (every WYSIWYG keystroke), and un-gated per-drain logging widens the
+ // witness-to-settle race window the canary e2e suite guards.
+ if (emittedClasses.length > 0) {
+ log.debug(
+ { site: opts.site, docName: opts.docName, classes: emittedClasses },
+ '[bridge-watchdog] tolerance classes applied',
+ );
+ }
for (const cls of emittedClasses) {
incrementBridgeToleranceApplied(cls);
console.warn(
@@ -621,10 +662,31 @@ export function assertBridgeInvariant(
// Production: rate-limited structured-log event.
const shouldEmit = shouldEmitBridgeInvariantViolation(opts.site, opts.docName, opts.nowMs);
if (!shouldEmit) {
+ // Counter-only on suppressed occurrences — a chronically-violating doc
+ // hits this per drain, so any per-occurrence logging or diff-summary
+ // computation here would add hot-path cost the debounce exists to
+ // avoid (see the tolerance-path breadcrumb rationale above).
incrementBridgeInvariantViolationsSuppressed();
return false;
}
incrementBridgeInvariantViolations();
+ // Content-free divergence summary — lengths + first-divergence offset
+ // only. Snapshot bytes are user content and must not reach the file sink
+ // (the redaction posture the hash-only console event already takes).
+ log.warn(
+ {
+ site: opts.site,
+ docName: opts.docName,
+ ytextBytes: ytextSnapshot.length,
+ fragmentBytes: fragmentMdSnapshot.length,
+ normalizedYtextBytes: ytextNorm.length,
+ normalizedFragmentBytes: fragNorm.length,
+ firstDivergenceIndex: firstDivergenceIndex(ytextNorm, fragNorm),
+ },
+ `[bridge-watchdog] bridge invariant violation at ${opts.site}${
+ opts.docName ? ` for '${opts.docName}'` : ''
+ }`,
+ );
// Default-redacted: `ytextHash`/`fragmentHash` (FNV-1a) replace raw `diff`
// bytes so log aggregators with weaker data-handling posture than the
// application store don't accumulate verbatim user content. Operators
diff --git a/packages/server/src/file-watcher-decision-ring.test.ts b/packages/server/src/file-watcher-decision-ring.test.ts
new file mode 100644
index 000000000..c42b349df
--- /dev/null
+++ b/packages/server/src/file-watcher-decision-ring.test.ts
@@ -0,0 +1,209 @@
+/**
+ * Watcher decision-ring coverage: the bounded record of recent file-watcher
+ * decisions (dispatched / self-write skips / drops) that backs the
+ * `/api/metrics/watcher-recent` endpoint and the `state/watcher-recent.jsonl`
+ * bundle artifact. Drives the ring through the real pipeline entry points
+ * (`handleRawEvents` / `classifyEvents`) so the recorded decisions reflect
+ * production drop sites, not a synthetic recorder.
+ */
+
+import { mkdirSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve, sep } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { createContentFilter } from './content-filter.ts';
+import type { DiskEvent, FileIndexEntry, FolderIndexEntry } from './file-watcher';
+import {
+ classifyEvents,
+ getWatcherDecisionRingSnapshot,
+ handleRawEvents,
+ lastKnownHash,
+ logWatcherDropSummary,
+ resetWatcherDecisionDiagnostics,
+ writeTracker,
+} from './file-watcher';
+import { getLogger } from './logger.ts';
+
+let tmpDir: string;
+let contentDir: string;
+
+beforeEach(async () => {
+ tmpDir = realpathSync(await mkdtemp(resolve(tmpdir(), 'ok-watcher-ring-')));
+ contentDir = resolve(tmpDir, 'content');
+ mkdirSync(contentDir, { recursive: true });
+ resetWatcherDecisionDiagnostics();
+ writeTracker.clear();
+ lastKnownHash.clear();
+});
+
+afterEach(async () => {
+ resetWatcherDecisionDiagnostics();
+ writeTracker.clear();
+ lastKnownHash.clear();
+ await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function runBatch(
+ rawEvents: Array<{ type: 'create' | 'update' | 'delete'; path: string }>,
+ contentFilter?: ReturnType<typeof createContentFilter>,
+): Promise<DiskEvent[]> {
+ const dispatched: DiskEvent[] = [];
+ await handleRawEvents(
+ rawEvents,
+ contentDir,
+ contentFilter,
+ new Map<string, FileIndexEntry>(),
+ new Map<string, FolderIndexEntry>(),
+ async (event) => {
+ dispatched.push(event);
+ },
+ );
+ return dispatched;
+}
+
+describe('watcher decision ring', () => {
+ test('dispatched markdown events are recorded with normalized paths', async () => {
+ const filePath = resolve(contentDir, 'notes', 'guide.md');
+ mkdirSync(resolve(contentDir, 'notes'), { recursive: true });
+ writeFileSync(filePath, '# Guide\n');
+
+ const dispatched = await runBatch([{ type: 'create', path: filePath }]);
+ expect(dispatched.some((e) => e.kind === 'create')).toBe(true);
+
+ const records = getWatcherDecisionRingSnapshot();
+ const record = records.find((r) => r.decision === 'dispatched' && r.kind === 'create');
+ expect(record).toBeDefined();
+ // Path is normalized to the last two segments — never the raw absolute path.
+ expect(record?.path).toBe(`...${sep}notes${sep}guide.md`);
+ expect(record?.path.includes(tmpDir)).toBe(false);
+ expect(record?.pathRole).toBe('content-md');
+ expect(record?.ts).toBeGreaterThan(0);
+ });
+
+ test('a symlink escaping contentDir records drop-symlink-escape and never dispatches', async () => {
+ const outsideTarget = resolve(tmpDir, 'outside.md');
+ writeFileSync(outsideTarget, '# Outside\n');
+ const linkPath = resolve(contentDir, 'escape.md');
+ symlinkSync(outsideTarget, linkPath);
+
+ const dispatched = await runBatch([{ type: 'create', path: linkPath }]);
+ expect(dispatched).toHaveLength(0);
+
+ const records = getWatcherDecisionRingSnapshot();
+ expect(records.some((r) => r.decision === 'drop-symlink-escape' && r.kind === 'create')).toBe(
+ true,
+ );
+ expect(records.some((r) => r.decision === 'dispatched')).toBe(false);
+ });
+
+ test('ContentFilter exclusion records drop-filter-excluded', async () => {
+ writeFileSync(resolve(tmpDir, '.gitignore'), 'dist/\n');
+ const filter = createContentFilter({ projectDir: tmpDir, contentDir });
+ mkdirSync(resolve(contentDir, 'dist'), { recursive: true });
+ const excludedPath = resolve(contentDir, 'dist', 'output.md');
+ writeFileSync(excludedPath, '# Build Output\n');
+
+ const events = await classifyEvents(
+ [{ type: 'create', path: excludedPath }],
+ contentDir,
+ filter,
+ );
+ expect(events).toHaveLength(0);
+
+ const records = getWatcherDecisionRingSnapshot();
+ const record = records.find((r) => r.decision === 'drop-filter-excluded');
+ expect(record).toBeDefined();
+ expect(record?.kind).toBe('create');
+ expect(record?.path).toBe(`...${sep}dist${sep}output.md`);
+ });
+
+ test('an unreadable create (delete race) records drop-read-failed', async () => {
+ const vanished = resolve(contentDir, 'vanished.md');
+
+ const events = await classifyEvents([{ type: 'create', path: vanished }], contentDir);
+ expect(events).toHaveLength(0);
+
+ const records = getWatcherDecisionRingSnapshot();
+ expect(records.some((r) => r.decision === 'drop-read-failed' && r.kind === 'create')).toBe(
+ true,
+ );
+ });
+
+ test('self-writes record self-write-skip instead of dispatched', async () => {
+ const filePath = resolve(contentDir, 'self.md');
+ const content = '# Self write\n';
+ writeFileSync(filePath, content);
+ const { registerWrite, contentHash } = await import('./file-watcher');
+ registerWrite(filePath, contentHash(content));
+
+ const dispatched = await runBatch([{ type: 'create', path: filePath }]);
+ expect(dispatched.some((e) => e.kind === 'create')).toBe(false);
+
+ const records = getWatcherDecisionRingSnapshot();
+ expect(records.some((r) => r.decision === 'self-write-skip' && r.kind === 'create')).toBe(true);
+ });
+
+ test('ring is bounded: oldest decisions are evicted past capacity', async () => {
+ // 300 unreadable creates → 300 drop-read-failed decisions; the ring
+ // retains only the newest 256.
+ for (let i = 0; i < 300; i++) {
+ await classifyEvents(
+ [{ type: 'create', path: resolve(contentDir, `missing-${i}.md`) }],
+ contentDir,
+ );
+ }
+ const records = getWatcherDecisionRingSnapshot();
+ expect(records).toHaveLength(256);
+ expect(records[0]?.path).toBe(`...${sep}content${sep}missing-44.md`);
+ expect(records.at(-1)?.path).toBe(`...${sep}content${sep}missing-299.md`);
+ });
+
+ test('snapshot returns copies — mutating a returned record does not corrupt the ring', async () => {
+ await classifyEvents([{ type: 'create', path: resolve(contentDir, 'gone.md') }], contentDir);
+ const first = getWatcherDecisionRingSnapshot();
+ const record = first[0];
+ expect(record).toBeDefined();
+ if (!record) return;
+ record.path = 'mutated';
+ expect(getWatcherDecisionRingSnapshot()[0]?.path).not.toBe('mutated');
+ });
+
+ test('resetWatcherDecisionDiagnostics clears the ring', async () => {
+ await classifyEvents([{ type: 'create', path: resolve(contentDir, 'gone.md') }], contentDir);
+ expect(getWatcherDecisionRingSnapshot().length).toBeGreaterThan(0);
+ resetWatcherDecisionDiagnostics();
+ expect(getWatcherDecisionRingSnapshot()).toHaveLength(0);
+ });
+});
+
+describe('watcher drop summary', () => {
+ test('emits only when drops accrued, with per-reason totals, then resets the window', async () => {
+ // The module-level `log` in file-watcher.ts is the factory-cached
+ // 'file-watcher' logger — spying on the cached instance intercepts the
+ // summary emission.
+ const infoSpy = vi.spyOn(getLogger('file-watcher'), 'info');
+ try {
+ logWatcherDropSummary();
+ expect(infoSpy).not.toHaveBeenCalled();
+
+ await classifyEvents(
+ [{ type: 'create', path: resolve(contentDir, 'missing.md') }],
+ contentDir,
+ );
+ logWatcherDropSummary();
+ expect(infoSpy).toHaveBeenCalledTimes(1);
+ const [payload] = infoSpy.mock.calls[0] ?? [];
+ expect(payload).toMatchObject({
+ droppedSinceLastSummary: 1,
+ dropTotals: { 'read-failed': 1 },
+ });
+
+ // Window reset: no new drops since the last summary → silent again.
+ logWatcherDropSummary();
+ expect(infoSpy).toHaveBeenCalledTimes(1);
+ } finally {
+ infoSpy.mockRestore();
+ }
+ });
+});
diff --git a/packages/server/src/file-watcher.ts b/packages/server/src/file-watcher.ts
index c830b9b01..640d9dcd1 100644
--- a/packages/server/src/file-watcher.ts
+++ b/packages/server/src/file-watcher.ts
@@ -324,6 +324,124 @@ export function contentHash(content: string): string {
return createHash('sha256').update(content).digest('hex');
}
+// ─── Watcher decision ring ──────────────────────────────────────────────────
+
+/**
+ * Bounded-cardinality reasons a raw watcher event never reaches
+ * `onDiskEvent`. Every silent `continue`/`filter` in the pipeline maps to
+ * one of these so "my file didn't sync" is diagnosable from a bundle
+ * instead of requiring a live repro.
+ */
+type WatcherDropReason =
+ | 'symlink-escape'
+ | 'filter-excluded'
+ | 'read-failed'
+ | 'reserved-doc'
+ | 'stat-failed';
+
+type WatcherDecision = 'dispatched' | 'self-write-skip' | `drop-${WatcherDropReason}`;
+
+/**
+ * One entry in the recent-decisions ring. `path` is pre-normalized via
+ * `normalizeFsPath` (last two segments) at record time — the ring is
+ * diagnostic data that lands in bundles and API responses, never a raw
+ * absolute path (cardinality + privacy rule shared with span attributes).
+ */
+export interface WatcherDecisionRecord {
+ ts: number;
+ decision: WatcherDecision;
+ /** Raw watcher event type (`create`/`update`/`delete`) or classified DiskEvent kind. */
+ kind: string;
+ path: string;
+ pathRole: string;
+}
+
+const WATCHER_DECISION_RING_CAPACITY = 256;
+const watcherDecisionRing: WatcherDecisionRecord[] = [];
+
+/** Cumulative per-reason drop totals since watcher start (summary payload). */
+const watcherDropCounts = new Map<WatcherDropReason, number>();
+let watcherDispatchedCount = 0;
+let watcherSelfWriteSkipCount = 0;
+/** Drops accrued since the last summary line — the summary emits only when non-zero. */
+let watcherDropsSinceLastSummary = 0;
+
+function recordWatcherDecision(decision: WatcherDecision, kind: string, rawPath: string): void {
+ watcherDecisionRing.push({
+ ts: Date.now(),
+ decision,
+ kind,
+ path: normalizeFsPath(rawPath),
+ pathRole: classifyFsPath(rawPath),
+ });
+ if (watcherDecisionRing.length > WATCHER_DECISION_RING_CAPACITY) {
+ watcherDecisionRing.shift();
+ }
+ if (decision === 'dispatched') {
+ watcherDispatchedCount++;
+ return;
+ }
+ if (decision === 'self-write-skip') {
+ watcherSelfWriteSkipCount++;
+ return;
+ }
+ const reason = decision.slice('drop-'.length) as WatcherDropReason;
+ watcherDropCounts.set(reason, (watcherDropCounts.get(reason) ?? 0) + 1);
+ watcherDropsSinceLastSummary++;
+ _fileWatcherDropsCounter().add(1, { 'disk.drop_reason': reason });
+}
+
+/**
+ * Snapshot the recent-decisions ring, oldest first. Entries are copies —
+ * callers (the `/api/metrics/watcher-recent` handler, tests) cannot mutate
+ * ring state through the returned array.
+ */
+export function getWatcherDecisionRingSnapshot(): WatcherDecisionRecord[] {
+ return watcherDecisionRing.map((record) => ({ ...record }));
+}
+
+/** How often the periodic drop-count summary line is considered (and emitted when drops accrued). */
+const WATCHER_DROP_SUMMARY_INTERVAL_MS = 60_000;
+
+/**
+ * Emit the periodic drop-count summary. Silent when no event was dropped
+ * since the previous summary — steady-state healthy watchers add zero log
+ * volume. Cumulative per-reason totals (not per-window deltas) so a single
+ * line orients a bundle reader without diffing successive summaries.
+ */
+export function logWatcherDropSummary(): void {
+ if (watcherDropsSinceLastSummary === 0) return;
+ const droppedSinceLastSummary = watcherDropsSinceLastSummary;
+ watcherDropsSinceLastSummary = 0;
+ const dropTotals: Record<string, number> = {};
+ for (const [reason, count] of watcherDropCounts) {
+ dropTotals[reason] = count;
+ }
+ log.info(
+ {
+ droppedSinceLastSummary,
+ dropTotals,
+ dispatched: watcherDispatchedCount,
+ selfWriteSkips: watcherSelfWriteSkipCount,
+ },
+ `[file-watcher] drop summary: ${droppedSinceLastSummary} event(s) dropped since last summary`,
+ );
+}
+
+/**
+ * Reset ring + counters. Called from `unsubscribe()` alongside the
+ * `writeTracker`/`lastKnownHash` clears (same rationale: successive
+ * watchers in one test process must not observe prior instances' state)
+ * and directly by unit tests.
+ */
+export function resetWatcherDecisionDiagnostics(): void {
+ watcherDecisionRing.length = 0;
+ watcherDropCounts.clear();
+ watcherDispatchedCount = 0;
+ watcherSelfWriteSkipCount = 0;
+ watcherDropsSinceLastSummary = 0;
+}
+
/**
* Detect a symlink whose canonical target escapes contentDir.
*
@@ -480,7 +598,10 @@ export async function classifyEvents(
// Apply content filter if provided
if (contentFilter) {
const relPath = toPosix(relative(contentDir, event.path));
- if (contentFilter.isExcluded(relPath)) continue;
+ if (contentFilter.isExcluded(relPath)) {
+ recordWatcherDecision('drop-filter-excluded', event.type, event.path);
+ continue;
+ }
}
switch (event.type) {
@@ -510,6 +631,10 @@ export async function classifyEvents(
try {
createContents.set(event.path, await readFile(event.path, 'utf-8'));
} catch (e) {
+ // ENOENT included: the file vanished between the kernel event and the
+ // read (delete race) — the event is silently dropped downstream, so the
+ // ring is the only record it ever existed.
+ recordWatcherDecision('drop-read-failed', event.type, event.path);
if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
log.warn({ path: event.path, err: e }, `Failed to read ${event.path}`);
}
@@ -519,6 +644,7 @@ export async function classifyEvents(
try {
updateContents.set(event.path, await readFile(event.path, 'utf-8'));
} catch (e) {
+ recordWatcherDecision('drop-read-failed', event.type, event.path);
if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
log.warn({ path: event.path, err: e }, `Failed to read ${event.path}`);
}
@@ -1255,6 +1381,10 @@ export async function handleRawEvents(
// content as a contentDir-scoped DiskEvent.
const safeEvents = rawEvents.filter((e) => {
if (!eventEscapesContentDir(e.path, contentDir)) return true;
+ // The escape check fails closed on unexpected lstat errors too; both
+ // shapes record under `symlink-escape` (the log line above carries the
+ // errno when it was a stat failure).
+ recordWatcherDecision('drop-symlink-escape', e.type, e.path);
log.warn({ path: e.path, type: e.type }, `Symlink escape: ${e.path}, dropping ${e.type} event`);
return false;
});
@@ -1285,7 +1415,11 @@ export async function handleRawEvents(
(path) =>
!batchPaths.has(path) && !lastKnownHash.has(path) && !knownCanonicalPaths.has(path),
)
- .filter((path) => !eventEscapesContentDir(path, contentDir))
+ .filter((path) => {
+ if (!eventEscapesContentDir(path, contentDir)) return true;
+ recordWatcherDecision('drop-symlink-escape', 'create', path);
+ return false;
+ })
.map((path) => ({ type: 'create' as const, path }));
if (rescuedCreates.length > 0) {
log.debug(
@@ -1415,6 +1549,11 @@ export async function handleRawEvents(
`[file-watcher] Skipped self-write: ${event.kind}`,
);
_fileWatcherEventsCounter().add(1, { 'disk.kind': event.kind, self: true });
+ recordWatcherDecision(
+ 'self-write-skip',
+ event.kind,
+ event.kind === 'rename' ? event.newPath : event.path,
+ );
continue;
}
@@ -1429,6 +1568,7 @@ export async function handleRawEvents(
// Normalize + classify the path to bound span-attribute cardinality
// (AGENTS.md STOP rule — raw paths blow up the trace index).
const rawPath = event.kind === 'rename' ? event.newPath : event.path;
+ recordWatcherDecision('dispatched', event.kind, rawPath);
await withSpan(
'file_watcher.process_event',
{
@@ -1445,6 +1585,7 @@ export async function handleRawEvents(
for (const event of folderEvents) {
log.debug({ kind: event.kind, path: event.path }, `[file-watcher] Dispatching: ${event.kind}`);
_fileWatcherEventsCounter().add(1, { 'disk.kind': event.kind, self: false });
+ recordWatcherDecision('dispatched', event.kind, event.path);
await withSpan(
'file_watcher.process_event',
{
@@ -1467,13 +1608,17 @@ export async function handleRawEvents(
for (const raw of assetEvents) {
if (contentFilter) {
const relPath = toPosix(relative(contentDir, raw.path));
- if (contentFilter.isExcluded(relPath)) continue;
+ if (contentFilter.isExcluded(relPath)) {
+ recordWatcherDecision('drop-filter-excluded', raw.type, raw.path);
+ continue;
+ }
}
const relativePath = toPosix(relative(contentDir, raw.path));
const event: DiskEvent =
raw.type === 'delete'
? { kind: 'asset-delete', path: raw.path, relativePath }
: { kind: 'asset-create', path: raw.path, relativePath };
+ recordWatcherDecision('dispatched', event.kind, raw.path);
await onDiskEvent(event);
}
@@ -1485,12 +1630,19 @@ export async function handleRawEvents(
// Filter through `isPathIgnored` (NOT `isExcluded`): see seed-walk rationale.
for (const raw of nonMdRawEvents) {
const relativePath = toPosix(relative(contentDir, raw.path));
- if (contentFilter?.isPathIgnored(relativePath)) continue;
- if (isSystemDoc(relativePath) || isConfigDoc(relativePath)) continue;
+ if (contentFilter?.isPathIgnored(relativePath)) {
+ recordWatcherDecision('drop-filter-excluded', raw.type, raw.path);
+ continue;
+ }
+ if (isSystemDoc(relativePath) || isConfigDoc(relativePath)) {
+ recordWatcherDecision('drop-reserved-doc', raw.type, raw.path);
+ continue;
+ }
if (raw.type === 'delete') {
const event: DiskEvent = { kind: 'file-delete', path: raw.path, relativePath };
updateFileIndex(event, fileIndex);
+ recordWatcherDecision('dispatched', event.kind, raw.path);
await onDiskEvent(event);
continue;
}
@@ -1508,11 +1660,14 @@ export async function handleRawEvents(
if (st.isSymbolicLink()) st = statSync(raw.path);
} catch (e) {
const code = (e as NodeJS.ErrnoException).code;
+ recordWatcherDecision('drop-stat-failed', raw.type, raw.path);
if (code !== 'ENOENT') {
log.warn({ path: raw.path, code }, `file-event lstat failed for ${raw.path} (${code})`);
}
continue;
}
+ // Not a drop: directory raw events reach here (nonMdRawEvents is only
+ // extension-filtered) and are handled by the folder pipeline above.
if (!st.isFile()) continue;
const event: DiskEvent =
@@ -1534,6 +1689,7 @@ export async function handleRawEvents(
inode: Number(st.ino),
};
updateFileIndex(event, fileIndex);
+ recordWatcherDecision('dispatched', event.kind, raw.path);
await onDiskEvent(event);
}
}
@@ -1546,6 +1702,14 @@ function _fileWatcherEventsCounter() {
return _fwEventsCounterCache;
}
+let _fwDropsCounterCache: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
+function _fileWatcherDropsCounter() {
+ _fwDropsCounterCache ||= getMeter().createCounter('ok.file_watcher.drops', {
+ description: 'File-watcher events dropped before dispatch, by bounded reason',
+ });
+ return _fwDropsCounterCache;
+}
+
// ─── Backend: @parcel/watcher ───────────────────────────────────────────────
async function startParcelWatcher(
@@ -1752,6 +1916,7 @@ export async function startWatcher(
bumpFileIndexGeneration();
const evictionInterval = setInterval(evictStaleTrackerEntries, WRITE_TRACKER_TTL_MS);
+ const dropSummaryInterval = setInterval(logWatcherDropSummary, WATCHER_DROP_SUMMARY_INTERVAL_MS);
let subscription: AsyncSubscription;
let backend: WatcherBackend;
@@ -1782,6 +1947,7 @@ export async function startWatcher(
}
} catch (e) {
clearInterval(evictionInterval);
+ clearInterval(dropSummaryInterval);
throw e;
}
@@ -1792,6 +1958,7 @@ export async function startWatcher(
return {
async unsubscribe() {
clearInterval(evictionInterval);
+ clearInterval(dropSummaryInterval);
// Clear the module-level writeTracker on unsubscribe so test suites
// that spin up successive watchers don't accumulate stale entries
// across instances. Production: unsubscribe = shutdown, no consumers
@@ -1799,6 +1966,7 @@ export async function startWatcher(
// the correct starting state for a fresh isolation boundary.
writeTracker.clear();
lastKnownHash.clear();
+ resetWatcherDecisionDiagnostics();
return originalUnsubscribe();
},
getFileIndex() {
diff --git a/packages/server/src/logger.test.ts b/packages/server/src/logger.test.ts
index 5c53b7126..e5e67eacc 100644
--- a/packages/server/src/logger.test.ts
+++ b/packages/server/src/logger.test.ts
@@ -1,10 +1,10 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'bun:test';
import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { context, trace } from '@opentelemetry/api';
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import {
createTestLogger,
getLogger,
@@ -270,9 +270,10 @@ describe('Logger', () => {
options: { level: 'info' },
fileSink: { projectDir: tmp, maxBytes: 1_000_000 },
});
- // Instance level must be the more-verbose of (file=info, console=warn)
- // so the logger-level gate doesn't drop INFO before per-stream filtering.
- expect(logger.getPinoInstance().level).toBe('info');
+ // Instance level must be the more-verbose of (file=debug, console=warn)
+ // so the logger-level gate doesn't drop DEBUG/INFO before per-stream
+ // filtering. The file sink defaults to debug (breadcrumb capture).
+ expect(logger.getPinoInstance().level).toBe('debug');
logger.info({}, 'info-to-disk');
logger.warn({}, 'warn-to-disk');
@@ -289,6 +290,56 @@ describe('Logger', () => {
}
});
+ it('DEBUG records reach the file sink by default without landing on stdout at the base level', async () => {
+ // Lifecycle breadcrumbs (agent sessions, bridge watchdog, watcher
+ // decisions) are emitted at debug — they must reach bug-report bundles
+ // (the file sink) while the terminal stays at the base level.
+ const logger = new PinoLogger('test', {
+ options: { level: 'info' },
+ fileSink: { projectDir: tmp, maxBytes: 1_000_000 },
+ });
+
+ logger.debug({ docName: 'x' }, 'debug-breadcrumb');
+ logger.info({}, 'info-line');
+ await logger.flushFileSink();
+
+ const records = await readLogLinesWhen(logsCurrentPath(tmp), 2);
+ expect(records.map((r) => r.msg)).toEqual(['debug-breadcrumb', 'info-line']);
+ expect(records[0]?.level).toBe(20); // pino debug level
+ });
+
+ it('OK_FILE_LEVEL overrides the file-sink level (opt-down from the debug default)', async () => {
+ const prev = process.env.OK_FILE_LEVEL;
+ process.env.OK_FILE_LEVEL = 'warn';
+ try {
+ const logger = new PinoLogger('test', {
+ options: { level: 'info' },
+ fileSink: { projectDir: tmp, maxBytes: 1_000_000 },
+ });
+ logger.debug({}, 'debug-filtered');
+ logger.info({}, 'info-filtered');
+ logger.warn({}, 'warn-to-disk');
+ await logger.flushFileSink();
+
+ const records = await readLogLinesWhen(logsCurrentPath(tmp), 1);
+ expect(records.map((r) => r.msg)).toEqual(['warn-to-disk']);
+ } finally {
+ if (prev === undefined) delete process.env.OK_FILE_LEVEL;
+ else process.env.OK_FILE_LEVEL = prev;
+ }
+ });
+
+ it('a silent base level keeps the file sink silent (test-logger contract)', async () => {
+ const logger = new PinoLogger('test', {
+ options: { level: 'silent' },
+ fileSink: { projectDir: tmp, maxBytes: 1_000_000 },
+ });
+ logger.debug({}, 'nope');
+ logger.error({}, 'also-nope');
+ await logger.flushFileSink();
+ expect(existsSync(logsCurrentPath(tmp))).toBe(false);
+ });
+
it('omits file destination when fileSink config is absent (no .ok/local/logs created)', async () => {
const logger = new PinoLogger('test', {
options: { level: 'info' },
diff --git a/packages/server/src/logger.ts b/packages/server/src/logger.ts
index 35c8ca0e6..7749ffc5d 100644
--- a/packages/server/src/logger.ts
+++ b/packages/server/src/logger.ts
@@ -148,26 +148,37 @@ export class PinoLogger {
}
/**
- * Resolve the effective per-stream levels. `fileLevel` is the configured
- * base level (what callers set via `options.level` / `LOG_LEVEL`) and
- * governs the on-disk sink. `consoleLevel` overrides the pretty stdout
- * stream from `OK_CONSOLE_LEVEL` when set to a valid level, else mirrors the
- * base. `instanceLevel` is the more-verbose of the two so the pino
+ * Resolve the effective per-stream levels. The base level (what callers set
+ * via `options.level` / `LOG_LEVEL`) governs the pretty stdout stream;
+ * `OK_CONSOLE_LEVEL` overrides it when set to a valid level. The on-disk
+ * sink (`fileLevel`) admits DEBUG by default — lifecycle breadcrumbs
+ * (agent sessions, bridge watchdog, watcher decisions) are emitted at
+ * debug so they reach bug-report bundles without spamming terminals; the
+ * sink's size-cap ring rotation bounds the disk cost. `OK_FILE_LEVEL`
+ * overrides the sink level, and a 'silent' base (tests) silences both
+ * streams. `instanceLevel` is the more-verbose of the two so the pino
* logger-level gate (which runs before per-stream filtering) admits every
* record either stream wants.
*
* This is what lets `ok start` keep the terminal legible (console raised to
- * 'warn') WITHOUT dropping the INFO diagnostics that bug-report bundles
- * depend on — those still land on the file sink at the base level.
+ * 'warn') WITHOUT dropping the DEBUG/INFO diagnostics that bug-report
+ * bundles depend on — those still land on the file sink.
*/
private resolveStreamLevels(): {
fileLevel: string;
consoleLevel: string;
instanceLevel: string;
} {
- const fileLevel = (this.options.level as string | undefined) ?? 'info';
+ const baseLevel = (this.options.level as string | undefined) ?? 'info';
+ const envFile = process.env.OK_FILE_LEVEL?.toLowerCase();
+ const fileLevel =
+ envFile && VALID_LOG_LEVELS.has(envFile)
+ ? envFile
+ : baseLevel === 'silent'
+ ? 'silent'
+ : mostVerboseLevel(baseLevel, 'debug');
const envConsole = process.env.OK_CONSOLE_LEVEL?.toLowerCase();
- const consoleLevel = envConsole && VALID_LOG_LEVELS.has(envConsole) ? envConsole : fileLevel;
+ const consoleLevel = envConsole && VALID_LOG_LEVELS.has(envConsole) ? envConsole : baseLevel;
return { fileLevel, consoleLevel, instanceLevel: mostVerboseLevel(fileLevel, consoleLevel) };
}