Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Shadow-repo self-maintenance + timeline resilience (PRD-6972) (#1839)
miles-kt-inkeep339b7edfe587
diff --git a/.changeset/shadow-repo-maintenance-timeline-resilience.md b/.changeset/shadow-repo-maintenance-timeline-resilience.mdnew file mode 100644index 000000000..a47084850--- /dev/null+++ b/.changeset/shadow-repo-maintenance-timeline-resilience.md@@ -0,0 +1,15 @@+---+"@inkeep/open-knowledge": minor+---++Keep history and Save Version responsive on long-lived, agent-heavy projects.++History stays fast no matter how long you have been working in a project, and+the version timeline keeps loading quickly even after months of daily edits.++Save Version now groups all of your recent changes — including changes made by+AI agents — under the version you save, matching what you would expect from the+button. Previously it only captured some of your recent activity.++`ok diagnose health` can now spot a project whose history has started to slow+down and explain what to do about it.diff --git a/packages/app/src/components/TimelinePanel.test.ts b/packages/app/src/components/TimelinePanel.test.tsindex 5177f11ff..2ffd63e8b 100644--- a/packages/app/src/components/TimelinePanel.test.ts+++ b/packages/app/src/components/TimelinePanel.test.ts@@ -51,6 +51,22 @@ describe('checkpointVariant', () => {),).toBe('external-change-rescue');});++ test('renders auto-consolidation checkpoints as "save" (D16 hidden by default, D17 no maintenance copy)', () => {+ const entry = baseEntry({+ checkpoint: {+ kind: 'auto-consolidation',+ docName: null,+ size: null,+ metadata: { foldedRefs: 6, trigger: 'dead-chain' },+ },+ });+ expect(checkpointVariant(entry)).toBe('save');+ const label = checkpointHeadlineLabel(entry);+ expect(label).toBe('Save Version');+ expect(label.toLowerCase()).not.toContain('consolidat');+ expect(label.toLowerCase()).not.toContain('maintenance');+ });});describe('checkpointHeadlineLabel (user-outcome language — review iteration 5)', () => {diff --git a/packages/app/src/components/TimelinePanel.tsx b/packages/app/src/components/TimelinePanel.tsxindex 50cd56e16..75a193c21 100644--- a/packages/app/src/components/TimelinePanel.tsx+++ b/packages/app/src/components/TimelinePanel.tsx@@ -51,6 +51,7 @@ import { Skeleton } from '@/components/ui/skeleton';import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';import { LruStringCache } from '@/lib/lru-string-cache';+import { createSelfSchedulingPoll, type PollOutcome } from '@/lib/self-scheduling-poll';import {HISTORICAL_CONTENT_CACHE_LIMIT,useTimelineEntryDiff,@@ -61,6 +62,41 @@ const LazyActivityPanelDiffView = lazy(async () => {return { default: mod.ActivityPanelDiffView };});+const TIMELINE_POLL_BASE_MS = 10_000;+const TIMELINE_POLL_MAX_BACKOFF_MS = 60_000;++async function pollHistoryOnce(+ docName: string,+ signal: AbortSignal,+ handlers: {+ setEntries: (entries: TimelineEntry[]) => void;+ setError: (message: string | null) => void;+ setLoading: (value: boolean) => void;+ unavailableMessage: string;+ },+): Promise<PollOutcome> {+ try {+ const res = await fetch(`/api/history?docName=${encodeURIComponent(docName)}&limit=100`, {+ signal,+ });+ if (!res.ok) {+ handlers.setError(handlers.unavailableMessage);+ return 'error';+ }+ const data = (await res.json()) as { entries: TimelineEntry[] };+ handlers.setEntries(data.entries ?? []);+ handlers.setError(null);+ return 'ok';+ } catch (e) {+ if (e instanceof DOMException && e.name === 'AbortError') throw e;+ handlers.setError(handlers.unavailableMessage);+ console.error('[timeline]', e);+ return 'error';+ } finally {+ if (!signal.aborted) handlers.setLoading(false);+ }+}+interface TimelineContentProps {docName: string;diffLayout: DiffLayout;@@ -230,6 +266,7 @@ type CheckpointVariant = 'save' | 'bridge-merge-loss' | 'external-change-rescue'export function checkpointVariant(entry: TimelineEntry): CheckpointVariant {if (!entry.checkpoint) return 'save';+ if (entry.checkpoint.kind === 'auto-consolidation') return 'save';return entry.checkpoint.kind;}@@ -649,7 +686,6 @@ export function TimelineContent({const [entries, setEntries] = useState<TimelineEntry[]>([]);const [loading, setLoading] = useState(false);const [error, setError] = useState<string | null>(null);- const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);const [cache] = useState(() => new LruStringCache(HISTORICAL_CONTENT_CACHE_LIMIT));const [expandedShas, setExpandedShas] = useState<Set<string>>(() => new Set());@@ -678,37 +714,31 @@ export function TimelineContent({return;}- let cancelled = false;-- async function fetchHistory() {- if (!docName) return;- try {- const res = await fetch(`/api/history?docName=${encodeURIComponent(docName)}&limit=100`);- if (cancelled) return;- if (!res.ok) {- setError(t`History unavailable`);- return;- }- const data = (await res.json()) as { entries: TimelineEntry[] };- if (cancelled) return;- setEntries(data.entries ?? []);- setError(null);- } catch (e) {- if (cancelled) return;- setError(t`History unavailable`);- console.error('[timeline]', e);- }- }-setLoading(true);- fetchHistory().finally(() => {- if (!cancelled) setLoading(false);+ const loop = createSelfSchedulingPoll({+ baseMs: TIMELINE_POLL_BASE_MS,+ maxBackoffMs: TIMELINE_POLL_MAX_BACKOFF_MS,+ isPaused: () => typeof document !== 'undefined' && document.visibilityState === 'hidden',+ poll: (signal) =>+ pollHistoryOnce(docName, signal, {+ setEntries,+ setError,+ setLoading,+ unavailableMessage: t`History unavailable`,+ }),});- intervalRef.current = setInterval(fetchHistory, 10_000);++ loop.start();+ const onVisibilityChange = () => loop.resume();+ if (typeof document !== 'undefined') {+ document.addEventListener('visibilitychange', onVisibilityChange);+ }return () => {- cancelled = true;- if (intervalRef.current) clearInterval(intervalRef.current);+ loop.stop();+ if (typeof document !== 'undefined') {+ document.removeEventListener('visibilitychange', onVisibilityChange);+ }};}, [docName, t]);diff --git a/packages/app/src/lib/self-scheduling-poll.test.ts b/packages/app/src/lib/self-scheduling-poll.test.tsnew file mode 100644index 000000000..9154cd0ec--- /dev/null+++ b/packages/app/src/lib/self-scheduling-poll.test.ts@@ -0,0 +1,230 @@+import { describe, expect, test } from 'bun:test';+import { createSelfSchedulingPoll, type PollOutcome } from './self-scheduling-poll.ts';++function makeTimerHarness() {+ const timers: Array<{ fn: () => void; ms: number; id: number }> = [];+ let nextId = 1;+ return {+ timers,+ setTimer: (fn: () => void, ms: number) => {+ const id = nextId++;+ timers.push({ fn, ms, id });+ return id;+ },+ clearTimer: (h: unknown) => {+ const i = timers.findIndex((t) => t.id === h);+ if (i >= 0) timers.splice(i, 1);+ },+ runPending: () => {+ const t = timers.shift();+ t?.fn();+ },+ };+}++function makePollController() {+ let calls = 0;+ let resolveLatest: (o: PollOutcome) => void = () => {};+ let rejectLatest: (e: unknown) => void = () => {};+ return {+ poll: (_signal: AbortSignal) => {+ calls += 1;+ return new Promise<PollOutcome>((res, rej) => {+ resolveLatest = res;+ rejectLatest = rej;+ });+ },+ get calls() {+ return calls;+ },+ resolve: (o: PollOutcome) => resolveLatest(o),+ reject: (e: unknown) => rejectLatest(e),+ };+}++const flush = async () => {+ await Promise.resolve();+ await Promise.resolve();+};++describe('createSelfSchedulingPoll (PRD-6972 FR1)', () => {+ test('never stacks: next poll is armed only after the previous settles', async () => {+ const timer = makeTimerHarness();+ const ctrl = makePollController();+ const loop = createSelfSchedulingPoll({+ poll: ctrl.poll,+ baseMs: 1000,+ maxBackoffMs: 60_000,+ isPaused: () => false,+ setTimer: timer.setTimer,+ clearTimer: timer.clearTimer,+ });++ loop.start();+ await flush();+ expect(ctrl.calls).toBe(1);+ expect(timer.timers).toHaveLength(0); // nothing armed while a poll is in flight++ await flush();+ expect(ctrl.calls).toBe(1);++ ctrl.resolve('ok');+ await flush();+ expect(timer.timers).toHaveLength(1); // next armed only after settle+ expect(timer.timers[0]?.ms).toBe(1000); // base cadence on success+ expect(ctrl.calls).toBe(1);++ timer.runPending();+ await flush();+ expect(ctrl.calls).toBe(2);+ loop.stop();+ });++ test('hidden tab issues zero requests; resume() restarts on re-show', async () => {+ const timer = makeTimerHarness();+ const ctrl = makePollController();+ let paused = false;+ const loop = createSelfSchedulingPoll({+ poll: ctrl.poll,+ baseMs: 1000,+ maxBackoffMs: 60_000,+ isPaused: () => paused,+ setTimer: timer.setTimer,+ clearTimer: timer.clearTimer,+ });++ loop.start();+ await flush();+ ctrl.resolve('ok');+ await flush();+ expect(timer.timers).toHaveLength(1);++ paused = true;+ timer.runPending();+ await flush();+ expect(ctrl.calls).toBe(1); // zero requests while hidden+ expect(timer.timers).toHaveLength(0); // parked, no timer++ loop.resume();+ await flush();+ expect(ctrl.calls).toBe(1);++ paused = false;+ loop.resume();+ await flush();+ expect(ctrl.calls).toBe(2);+ loop.stop();+ });++ test('errors back off exponentially up to the cap; success resets to base', async () => {+ const timer = makeTimerHarness();+ const ctrl = makePollController();+ const loop = createSelfSchedulingPoll({+ poll: ctrl.poll,+ baseMs: 1000,+ maxBackoffMs: 4000,+ isPaused: () => false,+ setTimer: timer.setTimer,+ clearTimer: timer.clearTimer,+ });++ loop.start();+ await flush();+ ctrl.resolve('error');+ await flush();+ expect(timer.timers[0]?.ms).toBe(2000); // base * 2++ timer.runPending();+ await flush();+ ctrl.resolve('error');+ await flush();+ expect(timer.timers[0]?.ms).toBe(4000); // 2000 * 2++ timer.runPending();+ await flush();+ ctrl.resolve('error');+ await flush();+ expect(timer.timers[0]?.ms).toBe(4000); // capped at max — no tight loop++ timer.runPending();+ await flush();+ ctrl.resolve('ok');+ await flush();+ expect(timer.timers[0]?.ms).toBe(1000); // recovered → base+ loop.stop();+ });++ test('a rejected poll backs off; a rejection after stop() does not reschedule', async () => {+ const timer = makeTimerHarness();+ const ctrl = makePollController();+ const loop = createSelfSchedulingPoll({+ poll: ctrl.poll,+ baseMs: 1000,+ maxBackoffMs: 60_000,+ isPaused: () => false,+ setTimer: timer.setTimer,+ clearTimer: timer.clearTimer,+ });++ loop.start();+ await flush();+ ctrl.reject(new Error('network'));+ await flush();+ expect(timer.timers[0]?.ms).toBe(2000); // rejection treated as error → backoff++ timer.runPending();+ await flush();+ loop.stop(); // aborts the in-flight poll+ ctrl.reject(new Error('aborted-after-stop'));+ await flush();+ expect(timer.timers).toHaveLength(0); // stopped → no reschedule+ });++ test('stop() clears the pending timer and start()/resume() are no-ops afterward', async () => {+ const timer = makeTimerHarness();+ const ctrl = makePollController();+ const loop = createSelfSchedulingPoll({+ poll: ctrl.poll,+ baseMs: 1000,+ maxBackoffMs: 60_000,+ isPaused: () => false,+ setTimer: timer.setTimer,+ clearTimer: timer.clearTimer,+ });++ loop.start();+ await flush();+ ctrl.resolve('ok');+ await flush();+ expect(timer.timers).toHaveLength(1);++ loop.stop();+ expect(timer.timers).toHaveLength(0); // pending timer cleared++ loop.start();+ loop.resume();+ await flush();+ expect(ctrl.calls).toBe(1); // no new poll after stop+ });++ test('a second start() while running is a no-op (does not spawn a second loop)', async () => {+ const timer = makeTimerHarness();+ const ctrl = makePollController();+ const loop = createSelfSchedulingPoll({+ poll: ctrl.poll,+ baseMs: 1000,+ maxBackoffMs: 60_000,+ isPaused: () => false,+ setTimer: timer.setTimer,+ clearTimer: timer.clearTimer,+ });++ loop.start();+ await flush();+ expect(ctrl.calls).toBe(1);++ loop.start();+ await flush();+ expect(ctrl.calls).toBe(1);+ });+});diff --git a/packages/app/src/lib/self-scheduling-poll.ts b/packages/app/src/lib/self-scheduling-poll.tsnew file mode 100644index 000000000..5707e23f0--- /dev/null+++ b/packages/app/src/lib/self-scheduling-poll.ts@@ -0,0 +1,89 @@+export type PollOutcome = 'ok' | 'error';++export interface SelfSchedulingPollOptions {+ poll: (signal: AbortSignal) => Promise<PollOutcome>;+ baseMs: number;+ maxBackoffMs: number;+ isPaused: () => boolean;+ setTimer?: (fn: () => void, ms: number) => unknown;+ clearTimer?: (handle: unknown) => void;+}++export interface SelfSchedulingPoll {+ /** Run the first poll and begin the loop. Idempotent: the first call starts the+ * loop; later calls (while running or after stop()) are no-ops. */+ start(): void;+ resume(): void;+ stop(): void;+}++export function createSelfSchedulingPoll(opts: SelfSchedulingPollOptions): SelfSchedulingPoll {+ const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));+ const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));++ let stopped = false;+ let started = false;+ let timer: unknown = null;+ let controller: AbortController | null = null;+ let backoffMs = opts.baseMs;+ let parked = false;++ const scheduleNext = (delayMs: number): void => {+ if (stopped) return;+ if (opts.isPaused()) {+ parked = true;+ return;+ }+ timer = setTimer(tick, delayMs);+ };++ async function tick(): Promise<void> {+ timer = null;+ parked = false;+ if (stopped) return;+ if (opts.isPaused()) {+ parked = true;+ return;+ }+ controller = new AbortController();+ const signal = controller.signal;+ try {+ const outcome = await opts.poll(signal);+ if (stopped) return;+ if (outcome === 'ok') {+ backoffMs = opts.baseMs;+ scheduleNext(opts.baseMs);+ } else {+ backoffMs = Math.min(backoffMs * 2, opts.maxBackoffMs);+ scheduleNext(backoffMs);+ }+ } catch {+ if (stopped || signal.aborted) return;+ backoffMs = Math.min(backoffMs * 2, opts.maxBackoffMs);+ scheduleNext(backoffMs);+ }+ }++ return {+ start() {+ if (stopped || started) return;+ started = true;+ void tick();+ },+ resume() {+ if (stopped) return;+ if (!opts.isPaused() && parked && timer === null) {+ parked = false;+ void tick();+ }+ },+ stop() {+ stopped = true;+ if (timer !== null) {+ clearTimer(timer);+ timer = null;+ }+ controller?.abort();+ },+ };+}diff --git a/packages/app/tests/integration/api-error-envelope/history.test.ts b/packages/app/tests/integration/api-error-envelope/history.test.tsindex eb7319416..4c6647ac5 100644--- a/packages/app/tests/integration/api-error-envelope/history.test.ts+++ b/packages/app/tests/integration/api-error-envelope/history.test.ts@@ -61,6 +61,26 @@ describe('history envelope (RFC 9457)', () => {}});+ test('concurrent identical requests stay consistent through the single-flight path (no shared-state corruption)', async () => {+ await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ docName: 'sf-doc', markdown: '# Coalesce\n', position: 'replace' }),+ });++ const url = `http://127.0.0.1:${server.port}/api/history?docName=sf-doc&limit=10`;+ const responses = await Promise.all(Array.from({ length: 8 }, () => fetch(url)));+ expect(responses.every((r) => r.status === 200)).toBe(true);+ const bodies = (await Promise.all(responses.map((r) => r.json()))) as Array<{+ entries: unknown[];+ hasMore?: boolean;+ }>;+ const first = JSON.stringify(bodies[0]?.entries);+ expect(bodies.every((b) => JSON.stringify(b.entries) === first)).toBe(true);+ const parsed = HistorySuccessSchema.safeParse(bodies[0]);+ expect(parsed.success).toBe(true);+ });+test('method-not-allowed on POST emits problem+json with Allow: GET', async () => {const res = await fetch(`http://127.0.0.1:${server.port}/api/history?docName=test-doc`, {method: 'POST',diff --git a/packages/cli/src/commands/diagnose-health-checks/index.ts b/packages/cli/src/commands/diagnose-health-checks/index.tsindex c01d336ae..88bc50b41 100644--- a/packages/cli/src/commands/diagnose-health-checks/index.ts+++ b/packages/cli/src/commands/diagnose-health-checks/index.ts@@ -6,6 +6,11 @@ export { makeMacosCodesigCheck } from './macos-codesig.ts';export { CHECK_NAMES, type CheckName, isCheckName } from './names.ts';export { DEFAULT_CHECK_TIMEOUT_MS, runAllChecks, runCheck } from './runner.ts';export { makeServerLockCheck } from './server-lock.ts';+export {+ makeShadowHealthCheck,+ type ShadowHealthCheckDeps,+ type ShadowHealthFacts,+} from './shadow-health.ts';export { makeShadowRepoCheck } from './shadow-repo.ts';export type {CheckContext,diff --git a/packages/cli/src/commands/diagnose-health-checks/names.ts b/packages/cli/src/commands/diagnose-health-checks/names.tsindex 94e358f9b..efce6f0cf 100644--- a/packages/cli/src/commands/diagnose-health-checks/names.ts+++ b/packages/cli/src/commands/diagnose-health-checks/names.ts@@ -5,6 +5,7 @@ export const CHECK_NAMES = ['content-dir','server-lock','shadow-repo',+ 'shadow-health','macos-codesig',] as const;diff --git a/packages/cli/src/commands/diagnose-health-checks/shadow-health.test.ts b/packages/cli/src/commands/diagnose-health-checks/shadow-health.test.tsnew file mode 100644index 000000000..759d00344--- /dev/null+++ b/packages/cli/src/commands/diagnose-health-checks/shadow-health.test.ts@@ -0,0 +1,142 @@+import { afterEach, describe, expect, test } from 'bun:test';+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { makeShadowHealthCheck, type ShadowHealthFacts } from './shadow-health.ts';++let tmpDirs: string[] = [];++afterEach(() => {+ for (const d of tmpDirs) {+ if (existsSync(d)) rmSync(d, { recursive: true, force: true });+ }+ tmpDirs = [];+});++function makeProjectWithShadow(): { cwd: string; shadowDir: string } {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-health-sh-'));+ tmpDirs.push(cwd);+ mkdirSync(join(cwd, '.git'), { recursive: true });+ const shadowDir = join(cwd, '.git', 'ok');+ mkdirSync(shadowDir, { recursive: true });+ return { cwd, shadowDir };+}++const HEALTHY: ShadowHealthFacts = {+ looseObjects: 40,+ packfiles: 2,+ wipWidth: 3,+ deadChains: 0,+ gcLogLatch: false,+ lastPackedAtMs: Date.now() - 60_000,+ lastConsolidationAtMs: Date.now() - 120_000,+};++function check(facts: ShadowHealthFacts, shadowDir: string) {+ return makeShadowHealthCheck({+ resolveDir: () => shadowDir,+ readFacts: async () => facts,+ });+}++describe('shadow-health check', () => {+ test('warns when .git/ is missing', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-health-nogit-'));+ tmpDirs.push(cwd);+ const result = await makeShadowHealthCheck().run({ cwd });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('no .git/');+ });++ test('warns when the shadow dir is not yet initialized', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'ok-health-noshadow-'));+ tmpDirs.push(cwd);+ mkdirSync(join(cwd, '.git'), { recursive: true });+ const def = makeShadowHealthCheck({ resolveDir: () => join(cwd, '.git', 'ok-missing') });+ const result = await def.run({ cwd });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('not yet initialized');+ });++ test('flags the incident-shaped repo as degraded with actionable detail', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const facts: ShadowHealthFacts = {+ looseObjects: 10_092,+ packfiles: 0,+ wipWidth: 57,+ deadChains: 41,+ gcLogLatch: true,+ lastPackedAtMs: null,+ lastConsolidationAtMs: null,+ };+ const result = await check(facts, shadowDir).run({ cwd });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('gc.log latch');+ expect(result.summary).toContain('10092 loose');+ expect(result.summary).toContain('57 WIP refs');+ expect(result.summary).toContain('41 dead chains');+ expect(result.detail).toContain('last packed: never');+ expect(result.remediation).toBeDefined();+ });++ test('stays quiet (pass) on a healthy repo', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check(HEALTHY, shadowDir).run({ cwd });+ expect(result.status).toBe('pass');+ expect(result.summary).toContain('40 loose');+ expect(result.summary).toContain('2 packs');+ });++ test('a gc.log latch alone trips the warn', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check({ ...HEALTHY, gcLogLatch: true }, shadowDir).run({ cwd });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('gc.log latch');+ });++ test('a wide journal alone trips the warn', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check({ ...HEALTHY, wipWidth: 40 }, shadowDir).run({ cwd });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('40 WIP refs');+ });++ test('unfolded dead chains trip the warn even when width is fine', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check({ ...HEALTHY, deadChains: 12 }, shadowDir).run({ cwd });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('12 dead chains');+ });++ test('dead-chain warn boundary: 5 stays quiet, 6 warns (strict >)', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const atThreshold = await check({ ...HEALTHY, deadChains: 5 }, shadowDir).run({ cwd });+ expect(atThreshold.status).toBe('pass');+ const over = await check({ ...HEALTHY, deadChains: 6 }, shadowDir).run({ cwd });+ expect(over.status).toBe('warn');+ expect(over.summary).toContain('6 dead chains');+ });++ test('heavy live load (wide journal, zero dead chains) does not warn on dead chains', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check({ ...HEALTHY, wipWidth: 50, deadChains: 0 }, shadowDir).run({ cwd });+ expect(result.status).toBe('warn'); // width still flags read latency+ expect(result.summary).toContain('50 WIP refs');+ expect(result.summary).not.toContain('dead chains');+ });++ test('a never-packed repo (0 packfiles, loose over gc.auto) trips the warn', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check({ ...HEALTHY, packfiles: 0, looseObjects: 800 }, shadowDir).run({+ cwd,+ });+ expect(result.status).toBe('warn');+ expect(result.summary).toContain('never packed');+ });++ test('does not leak KB-owner-facing consolidation/maintenance marketing copy', async () => {+ const { cwd, shadowDir } = makeProjectWithShadow();+ const result = await check({ ...HEALTHY, wipWidth: 40 }, shadowDir).run({ cwd });+ expect(result.summary.toLowerCase()).not.toContain('save version');+ });+});diff --git a/packages/cli/src/commands/diagnose-health-checks/shadow-health.ts b/packages/cli/src/commands/diagnose-health-checks/shadow-health.tsnew file mode 100644index 000000000..96f105b2f--- /dev/null+++ b/packages/cli/src/commands/diagnose-health-checks/shadow-health.ts@@ -0,0 +1,186 @@+import { existsSync, statSync } from 'node:fs';+import { resolve } from 'node:path';+import { parseCheckpoint, resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import {+ countShadowObjects,+ countStaleAgentWipRefs,+ countWipRefs,+ hasGcLogLatch,+} from '@inkeep/open-knowledge-server';+import simpleGit from 'simple-git';+import type { CheckContext, CheckDefinition, CheckResult } from './types.ts';++const LOOSE_WARN = 2000;+const WIDTH_WARN = 20;+const DEAD_CHAIN_WARN = 5;+const DEAD_CHAIN_STALE_MS = 30 * 60 * 1000;++export interface ShadowHealthFacts {+ looseObjects: number;+ packfiles: number;+ wipWidth: number;+ /** Dead `agent-*` chains unfolded past the staleness window — the strict+ * auto-consolidation-health signal (near zero when the fast path keeps up,+ * unlike raw width which counts live sessions too). `principal-*` chains are+ * excluded: they fold on the 30-day TTL, not this fast path. */+ deadChains: number;+ gcLogLatch: boolean;+ lastPackedAtMs: number | null;+ lastConsolidationAtMs: number | null;+}++export interface ShadowHealthCheckDeps {+ resolveDir?: (projectRoot: string) => string;+ readFacts?: (shadowDir: string, cwd: string) => Promise<ShadowHealthFacts>;+}++async function defaultReadFacts(shadowDir: string, cwd: string): Promise<ShadowHealthFacts> {+ const handle = { gitDir: shadowDir, workTree: cwd };+ const objects = await countShadowObjects(handle);+ const wipWidth = await countWipRefs(handle);+ const deadChains = await countStaleAgentWipRefs(handle, Date.now() - DEAD_CHAIN_STALE_MS);+ const gcLogLatch = hasGcLogLatch(handle);++ let lastPackedAtMs: number | null = null;+ for (const rel of ['objects/info/commit-graph', 'objects/info/commit-graphs']) {+ const p = resolve(shadowDir, rel);+ if (existsSync(p)) {+ try {+ lastPackedAtMs = Math.max(lastPackedAtMs ?? 0, statSync(p).mtimeMs);+ } catch {}+ }+ }++ let lastConsolidationAtMs: number | null = null;+ try {+ const sg = simpleGit({ baseDir: cwd, timeout: { block: 4000 } }).env({ GIT_DIR: shadowDir });+ const shas = (+ await sg.raw(+ 'for-each-ref',+ '--sort=-creatordate',+ '--format=%(objectname)',+ 'refs/checkpoints/',+ )+ )+ .trim()+ .split('\n')+ .filter(Boolean)+ .slice(0, 25);+ for (const sha of shas) {+ const out = (await sg.raw('log', '-1', '--format=%cI%x00%B', sha)).trim();+ const nul = out.indexOf('\x00');+ if (nul < 0) continue;+ const iso = out.slice(0, nul);+ const body = out.slice(nul + 1);+ if (parseCheckpoint(body)?.kind === 'auto-consolidation') {+ const ms = Date.parse(iso);+ if (Number.isFinite(ms)) lastConsolidationAtMs = ms;+ break; // sorted newest-first+ }+ }+ } catch {}++ return {+ looseObjects: objects.looseObjects,+ packfiles: objects.packfiles,+ wipWidth,+ deadChains,+ gcLogLatch,+ lastPackedAtMs,+ lastConsolidationAtMs,+ };+}++function relTime(ms: number | null): string {+ if (ms === null) return 'never';+ const ageMs = Date.now() - ms;+ const days = ageMs / (24 * 60 * 60 * 1000);+ if (days >= 1) return `${Math.round(days)}d ago`;+ const hours = ageMs / (60 * 60 * 1000);+ if (hours >= 1) return `${Math.round(hours)}h ago`;+ return `${Math.max(0, Math.round(ageMs / 60000))}m ago`;+}++export function makeShadowHealthCheck(deps: ShadowHealthCheckDeps = {}): CheckDefinition {+ const resolveDir = deps.resolveDir ?? resolveShadowDir;+ const readFacts = deps.readFacts ?? defaultReadFacts;+ return {+ name: 'shadow-health',+ run: async (ctx: CheckContext): Promise<CheckResult> => {+ const gitDir = resolve(ctx.cwd, '.git');+ if (!existsSync(gitDir)) {+ return {+ name: 'shadow-health',+ status: 'warn',+ summary: 'no .git/ at project root (shadow repo not initialized)',+ remediation: 'Run `ok start` once to initialize the shadow repo.',+ };+ }+ let shadowDir: string;+ try {+ shadowDir = resolveDir(ctx.cwd);+ } catch (err) {+ return {+ name: 'shadow-health',+ status: 'warn',+ summary: `cannot resolve shadow gitdir: ${err instanceof Error ? err.message : String(err)}`,+ };+ }+ if (!existsSync(shadowDir)) {+ return {+ name: 'shadow-health',+ status: 'warn',+ summary: 'shadow repo not yet initialized',+ remediation: 'Run `ok start` once to initialize the shadow repo.',+ };+ }++ const facts = await readFacts(shadowDir, ctx.cwd);+ const reasons: string[] = [];+ if (facts.gcLogLatch) {+ reasons.push('gc.log latch present (auto-packing disabled until it self-expires)');+ }+ if (facts.looseObjects > LOOSE_WARN) {+ reasons.push(`${facts.looseObjects} loose objects (unpacked)`);+ } else if (facts.packfiles === 0 && facts.looseObjects > 512) {+ reasons.push(`${facts.looseObjects} loose objects, never packed`);+ }+ if (facts.deadChains > DEAD_CHAIN_WARN) {+ reasons.push(+ `${facts.deadChains} dead chains unfolded (auto-consolidation not keeping up)`,+ );+ }+ if (facts.wipWidth > WIDTH_WARN) {+ reasons.push(`${facts.wipWidth} WIP refs (version-journal width high)`);+ }++ const detail = [+ `loose objects: ${facts.looseObjects}`,+ `packfiles: ${facts.packfiles}`,+ `WIP refs: ${facts.wipWidth}`,+ `dead chains: ${facts.deadChains}`,+ `gc.log latch: ${facts.gcLogLatch ? 'present' : 'none'}`,+ `last packed: ${relTime(facts.lastPackedAtMs)}`,+ `last fold: ${relTime(facts.lastConsolidationAtMs)}`,+ ].join(', ');++ if (reasons.length > 0) {+ return {+ name: 'shadow-health',+ status: 'warn',+ summary: `history may be slow: ${reasons.join('; ')}`,+ remediation:+ 'Packing and journal cleanup run automatically on the next server start and during use. If this persists, check the server logs.',+ detail,+ };+ }++ return {+ name: 'shadow-health',+ status: 'pass',+ summary: `${facts.looseObjects} loose, ${facts.packfiles} packs, ${facts.wipWidth} WIP refs`,+ detail,+ };+ },+ };+}diff --git a/packages/cli/src/commands/diagnose-health.ts b/packages/cli/src/commands/diagnose-health.tsindex 1a17a89aa..7965c5ecb 100644--- a/packages/cli/src/commands/diagnose-health.ts+++ b/packages/cli/src/commands/diagnose-health.ts@@ -12,6 +12,7 @@ import {makeGitCheck,makeMacosCodesigCheck,makeServerLockCheck,+ makeShadowHealthCheck,makeShadowRepoCheck,runAllChecks,} from './diagnose-health-checks/index.ts';@@ -39,6 +40,7 @@ export function defaultChecks(): CheckDefinition[] {makeContentDirCheck(),makeServerLockCheck(),makeShadowRepoCheck(),+ makeShadowHealthCheck(),makeMacosCodesigCheck(),];}diff --git a/packages/core/src/schemas/api/history.ts b/packages/core/src/schemas/api/history.tsindex 4e8550afd..8cadea4d0 100644--- a/packages/core/src/schemas/api/history.ts+++ b/packages/core/src/schemas/api/history.ts@@ -59,6 +59,7 @@ export const HistorySuccessSchema = zentries: z.array(HistoryEntrySchema),total: z.number().int().nonnegative().optional(),truncated: z.boolean().optional(),+ hasMore: z.boolean().optional(),}).loose() satisfies StandardSchemaV1;export type HistorySuccess = z.infer<typeof HistorySuccessSchema>;diff --git a/packages/core/src/shadow-repo-layout.test.ts b/packages/core/src/shadow-repo-layout.test.tsindex 15ab09055..ead78fcc0 100644--- a/packages/core/src/shadow-repo-layout.test.ts+++ b/packages/core/src/shadow-repo-layout.test.ts@@ -722,6 +722,56 @@ describe('parseCheckpoint / formatCheckpointBodyLine (bridge-correctness SPEC §const checkpoint = parseCheckpoint(body);expect(checkpoint?.kind).toBe('bridge-merge-loss');});++ test('round-trips auto-consolidation with foldedRefs + trigger', () => {+ const line = formatCheckpointBodyLine({+ kind: 'auto-consolidation',+ docName: null,+ size: null,+ metadata: { foldedRefs: 7, trigger: 'dead-chain' },+ });+ const body = `checkpoint: Consolidated 7 inactive sessions\n\n${line}`;+ const parsed = parseCheckpoint(body);+ expect(parsed?.kind).toBe('auto-consolidation');+ if (parsed?.kind === 'auto-consolidation') {+ expect(parsed.metadata.foldedRefs).toBe(7);+ expect(parsed.metadata.trigger).toBe('dead-chain');+ }+ });++ test('auto-consolidation: malformed metadata returns null (foldedRefs/trigger required)', () => {+ expect(+ parseCheckpoint(+ '\nok-checkpoint-v1: {"kind":"auto-consolidation","metadata":{"foldedRefs":3}}',+ ),+ ).toBe(null);+ expect(+ parseCheckpoint(+ '\nok-checkpoint-v1: {"kind":"auto-consolidation","metadata":{"trigger":"boot"}}',+ ),+ ).toBe(null);+ });++ test('auto-consolidation: trigger parses as a bare string (forward-compat with new triggers)', () => {+ const parsed = parseCheckpoint(+ '\nok-checkpoint-v1: {"kind":"auto-consolidation","metadata":{"foldedRefs":1,"trigger":"some-future-trigger"}}',+ );+ expect(parsed?.kind).toBe('auto-consolidation');+ if (parsed?.kind === 'auto-consolidation') {+ expect(parsed.metadata.trigger).toBe('some-future-trigger');+ }+ });++ test('D22: a reader lacking the auto-consolidation branch treats it as untyped (null)', () => {+ const line = formatCheckpointBodyLine({+ kind: 'auto-consolidation',+ docName: null,+ size: null,+ metadata: { foldedRefs: 2, trigger: 'boot' },+ });+ expect(line.startsWith('ok-checkpoint-v1: ')).toBe(true);+ expect(JSON.parse(line.slice('ok-checkpoint-v1: '.length)).kind).toBe('auto-consolidation');+ });});describe('formatWipSubject', () => {diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.tsindex 81826943b..d5fcd3f34 100644--- a/packages/core/src/shadow-repo-layout.ts+++ b/packages/core/src/shadow-repo-layout.ts@@ -266,6 +266,8 @@ export function parseContributors(body: string): ShadowContributor[] {const OK_CHECKPOINT_PREFIX = 'ok-checkpoint-v1: ';+export type AutoConsolidationTrigger = 'dead-chain' | 'session-close' | 'boot' | 'ttl';+export type ParsedCheckpoint =| {kind: 'bridge-merge-loss';@@ -278,6 +280,12 @@ export type ParsedCheckpoint =docName: string | null;size: number | null;metadata: { incomingDiskSha: string };+ }+ | {+ kind: 'auto-consolidation';+ docName: string | null;+ size: number | null;+ metadata: { foldedRefs: number; trigger: string };};export function parseCheckpoint(body: string): ParsedCheckpoint | null {@@ -327,6 +335,22 @@ export function parseCheckpoint(body: string): ParsedCheckpoint | null {}return null;}+ if (kind === 'auto-consolidation') {+ const m = metadata as { foldedRefs?: unknown; trigger?: unknown };+ if (+ typeof m.foldedRefs === 'number' &&+ Number.isFinite(m.foldedRefs) &&+ typeof m.trigger === 'string'+ ) {+ return {+ kind: 'auto-consolidation',+ docName,+ size,+ metadata: { foldedRefs: m.foldedRefs, trigger: m.trigger },+ };+ }+ return null;+ }return null;}return null;diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex d60dae15a..9b0621cba 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -442,6 +442,7 @@ import {} from './seed/index.ts';import type { PairedWriteOrigin } from './server-observers.ts';import {+ enumerateWipChains,listRescueCheckpoints,SERVICE_WRITER,type ShadowRef,@@ -451,11 +452,13 @@ import {type TimelineRescueEntry,type WriterIdentity,} from './shadow-repo.ts';+import { createSingleFlight } from './single-flight.ts';import { SuggestLinksTargetNotFoundError, suggestLinks } from './suggest-links.ts';import type { SyncEngine } from './sync-engine.ts';import type { TagIndex } from './tag-index.ts';import { getMeter, getTracer, withSpan, withSpanSync } from './telemetry.ts';import { getDocumentHistory, getFolderTimeline } from './timeline-query.ts';+import { recordTimelineCoalesced } from './timeline-telemetry.ts';let _httpDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHistogram']> {@@ -1669,6 +1672,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {const localOpGuard = createConcurrencyGuard();const showAllInflight = new Map<string, InflightShowAllWalk>();++ const historyInflight = createSingleFlight<Awaited<ReturnType<typeof getDocumentHistory>>>();let referencedAssetsCache: {signature: string;assets: ReturnType<typeof collectReferencedAssets>;@@ -5159,6 +5164,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;let writers: WriterIdentity[] = [];+ let foldEnumeratedAll = false;if (Array.isArray(body.writers)) {try {@@ -5185,6 +5191,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {}}+ const saveVersionBranch = getCurrentBranch?.() ?? 'main';+if (writers.length === 0) {if (svRawAgentId !== undefined) {const displayName = svClientName ? `${svAgentName} (${svClientName})` : svAgentName;@@ -5192,7 +5200,17 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {{ id: svAgentId, name: displayName, email: `${svAgentId}@openknowledge.local` },];} else {- writers = [SERVICE_WRITER];+ const chains = await enumerateWipChains(shadow, saveVersionBranch);+ const foldable = chains.filter((c) => !c.isPark);+ writers =+ foldable.length > 0+ ? foldable.map((c) => ({+ id: c.writerId,+ name: c.writerId,+ email: `${c.writerId}@openknowledge.local`,+ }))+ : [SERVICE_WRITER];+ foldEnumeratedAll = true;}}@@ -5204,8 +5222,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {shadow,resolvedContentRoot,writers,- 'main',+ saveVersionBranch,checkpointSummary.kind === 'value' ? checkpointSummary.value : undefined,+ foldEnumeratedAll ? { includeUpstream: false } : undefined,);getLogger('history').info({ checkpointRef: result.checkpointRef }, 'checkpoint');@@ -5280,11 +5299,16 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {const folderLimit = Math.min(200, Number.isFinite(rawFolderLimit) ? rawFolderLimit : 50);const rawFolderOffset = Number(url.searchParams.get('offset') ?? '0');const folderOffset = Math.max(0, Number.isFinite(rawFolderOffset) ? rawFolderOffset : 0);- const result = await getFolderTimeline(shadow, validated.folderRel, contentRoot ?? '.', {- branch,- limit: folderLimit,- offset: folderOffset,- });+ const folderKey = `folder\0${branch}\0${validated.folderRel}\0${folderLimit}\0${folderOffset}`;+ const { promise, coalesced } = historyInflight.run(folderKey, () =>+ getFolderTimeline(shadow, validated.folderRel, contentRoot ?? '.', {+ branch,+ limit: folderLimit,+ offset: folderOffset,+ }),+ );+ if (coalesced) recordTimelineCoalesced('folder');+ const result = await promise;successResponse(res, 200, HistorySuccessSchema, { ...result }, { handler: 'history' });return;}@@ -5305,22 +5329,30 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {const type = url.searchParams.get('type') ?? undefined;const author = url.searchParams.get('author') ?? undefined;const excludeAuthor = url.searchParams.get('excludeAuthor') ?? undefined;+ const includeAutoCheckpoints = url.searchParams.get('includeAutoCheckpoints') === 'true';++ const docKey = `doc\0${branch}\0${docName}\0${limit}\0${offset}\0${type ?? ''}\0${author ?? ''}\0${excludeAuthor ?? ''}\0${includeAutoCheckpoints ? '1' : '0'}`;const t0 = Date.now();try {- const result = await getDocumentHistory(- shadow,- {- docName,- branch,- limit,- offset,- type,- author,- excludeAuthor,- },- resolvedContentRoot,+ const { promise, coalesced } = historyInflight.run(docKey, () =>+ getDocumentHistory(+ shadow,+ {+ docName,+ branch,+ limit,+ offset,+ type,+ author,+ excludeAuthor,+ includeAutoCheckpoints,+ },+ resolvedContentRoot,+ ),);+ if (coalesced) recordTimelineCoalesced('doc');+ const result = await promise;const duration = Date.now() - t0;getLogger('timeline').info(diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex 9fba97e5b..94b6ec5fa 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -297,6 +297,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {sessionManager,agentFocusBroadcaster,agentPresenceBroadcaster,+ maintenanceCoordinator,} = serverInstance;const mcpHost = (() => {@@ -372,6 +373,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {sessionManager,agentFocusBroadcaster,agentPresenceBroadcaster,+ maintenanceCoordinator,keepaliveGraceMs: opts.keepaliveGraceMs,contentAssetMiddleware,reactShellMiddleware,diff --git a/packages/server/src/content/shadow-log.test.ts b/packages/server/src/content/shadow-log.test.tsindex 37a6db278..db4c2318f 100644--- a/packages/server/src/content/shadow-log.test.ts+++ b/packages/server/src/content/shadow-log.test.ts@@ -7,15 +7,36 @@ import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';+import { formatOkActor, type OkActorEntry } from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';import {commitUpstreamImport,commitWip,initShadowRepo,+ saveVersion,type WriterIdentity,} from '../shadow-repo.ts';import { readShadowLog } from './shadow-log.ts';+/** Build a realistic WIP commit body with an ok-actor line (as the persistence+ * write path does in production — the saveVersion fallback attributes from it). */+function wipBody(subject: string, writerId: string, displayName: string): string {+ const actor: OkActorEntry = {+ v: 1,+ writer_id: writerId,+ principal: null,+ agent_session: writerId,+ agent_type: null,+ client_name: null,+ client_version: null,+ label: null,+ display_name: displayName,+ color_seed: writerId,+ docs: ['content/auth'],+ };+ return `${subject}\n\n${formatOkActor(actor)}`;+}+let tmpDir: string;beforeEach(async () => {@@ -236,3 +257,49 @@ describe('readShadowLog — FR14 summaries carry through (US-007)', () => {expect(commits[0].contributors[0].summaries).toBeUndefined();});});++describe('readShadowLog — checkpoint-ancestry fallback (PRD-6972 FR7 / D15)', () => {+ test('enriched read parity across a consolidation (WIP refs gone, checkpoint anchors)', async () => {+ const project = await bootstrapProject();+ const shadow = await initShadowRepo(project);+ const contentDir = resolve(project, 'content');+ mkdirSync(contentDir, { recursive: true });+ const branch = (await simpleGit(project).revparse(['--abbrev-ref', 'HEAD'])).trim();+ const writer: WriterIdentity = { id: 'agent-z', name: 'Agent Z', email: '[email protected]' };++ for (let i = 1; i <= 3; i++) {+ writeFileSync(resolve(contentDir, 'auth.md'), `# v${i}\n`);+ await commitWip(+ shadow,+ writer,+ contentDir,+ wipBody(`edit ${i}`, 'agent-z', 'Agent Z'),+ branch,+ );+ await wait(5);+ }++ const before = await readShadowLog(project, 'content/auth.md', 5);+ expect(before.commits.length).toBe(3);++ await saveVersion(shadow, contentDir, [writer], branch, undefined, {+ checkpointKind: { foldedRefs: 1, trigger: 'dead-chain' },+ });++ const after = await readShadowLog(project, 'content/auth.md', 5);+ expect(after.commits.map((c) => c.hash).sort()).toEqual(+ before.commits.map((c) => c.hash).sort(),+ );+ expect(after.commits.every((c) => !c.message.startsWith('checkpoint:'))).toBe(true);+ expect(after.commits.every((c) => c.writerId === 'agent-z')).toBe(true);+ expect(after.commits.every((c) => c.writerClassification === 'agent')).toBe(true);+ });++ test('no checkpoint + no WIP refs → still empty (no false fallback)', async () => {+ const project = await bootstrapProject();+ await initShadowRepo(project);+ const result = await readShadowLog(project, 'content/auth.md', 5);+ expect(result.source).toBe('shadow-repo');+ expect(result.commits).toEqual([]);+ });+});diff --git a/packages/server/src/content/shadow-log.ts b/packages/server/src/content/shadow-log.tsindex 048ddbcc8..a9cdfa40b 100644--- a/packages/server/src/content/shadow-log.ts+++ b/packages/server/src/content/shadow-log.ts@@ -3,6 +3,7 @@ import type { ShadowContributor } from '@inkeep/open-knowledge-core';import {getShadowRepoPath,getWipRefPattern,+ parseOkActor,parseWriterId,readContributors,type WriterClassification,@@ -99,6 +100,79 @@ async function logOnRef(return commits;}+async function checkpointAncestryFallback(+ sg: SimpleGit,+ branch: string,+ relPath: string,+ need: number,+ seen: Set<string>,+): Promise<ShadowCommit[]> {+ let latestCheckpoint = '';+ try {+ latestCheckpoint = (+ await sg.raw(+ 'for-each-ref',+ '--sort=-creatordate',+ '--count=1',+ '--format=%(objectname)',+ `refs/checkpoints/${branch}/`,+ )+ ).trim();+ } catch {+ return [];+ }+ if (!latestCheckpoint) return [];++ let out = '';+ try {+ out = await sg.raw(+ 'log',+ latestCheckpoint,+ `-${Math.max(need * 3, 20)}`,+ '--format=%H%x00%aI%x00%an%x00%s%x00%B%x1e',+ '--',+ relPath,+ );+ } catch {+ return [];+ }++ const commits: ShadowCommit[] = [];+ for (const record of out.split('\x1e')) {+ if (commits.length >= need) break;+ const trimmed = record.trimStart();+ if (!trimmed) continue;+ const [hash = '', date = '', authorName = '', subject = '', rawBody = ''] =+ trimmed.split('\x00');+ const sha = hash.trim();+ if (sha.length !== 40 || seen.has(sha)) continue;+ if (+ subject.startsWith('checkpoint:') ||+ subject.startsWith('park:') ||+ subject.startsWith('import:') ||+ subject.startsWith('upstream:')+ ) {+ continue;+ }+ const actor = parseOkActor(rawBody);+ const writerId = actor?.writer_id ?? '';+ const parsed = parseWriterId(writerId);+ seen.add(sha);+ commits.push({+ hash: sha,+ date,+ writerName: actor?.display_name ?? authorName,+ message: subject,+ contributors: readContributors(rawBody),+ writerId,+ isAgent: parsed.isAgent,+ writerClassification: parsed.classification,+ branch,+ });+ }+ return commits;+}+export async function readShadowLog(projectDir: string,relPath: string,@@ -122,13 +196,31 @@ export async function readShadowLog(.split('\n').map((r) => r.trim()).filter(Boolean);- if (refs.length === 0) return { commits: [], source: 'shadow-repo' };- const perRef = await Promise.all(refs.map((ref) => logOnRef(sg, ref, relPath, branch, limit)));- const commits = perRef+ const perRef =+ refs.length === 0+ ? []+ : await Promise.all(refs.map((ref) => logOnRef(sg, ref, relPath, branch, limit)));+ let commits = perRef.flat().sort((a, b) => b.date.localeCompare(a.date)).slice(0, limit);+ if (commits.length < limit) {+ const seen = new Set(commits.map((c) => c.hash));+ const fallback = await checkpointAncestryFallback(+ sg,+ branch,+ relPath,+ limit - commits.length,+ seen,+ );+ if (fallback.length > 0) {+ commits = [...commits, ...fallback]+ .sort((a, b) => b.date.localeCompare(a.date))+ .slice(0, limit);+ }+ }+return { commits, source: 'shadow-repo' };}diff --git a/packages/server/src/incident-replay.test.ts b/packages/server/src/incident-replay.test.tsnew file mode 100644index 000000000..ae43acc45--- /dev/null+++ b/packages/server/src/incident-replay.test.ts@@ -0,0 +1,273 @@+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { mkdirSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { metrics } from '@opentelemetry/api';+import {+ AggregationTemporality,+ InMemoryMetricExporter,+ MeterProvider,+ PeriodicExportingMetricReader,+} from '@opentelemetry/sdk-metrics';+import simpleGit from 'simple-git';+import { createMaintenanceCoordinator } from './maintenance-coordinator.ts';+import {+ __resetMaintenanceTelemetryForTesting,+ recordConsolidation,+ recordGcLatch,+ recordMaintenanceRun,+} from './shadow-maintenance-telemetry.ts';+import { commitWip, initShadowRepo, type ShadowHandle } from './shadow-repo.ts';+import { countShadowObjects, countWipRefs, hasGcLogLatch } from './shadow-repo-stats.ts';+import {+ __resetTimelineTelemetryForTesting,+ commitsBucket,+ recordTimelineCoalesced,+ recordTimelineQuery,+ widthBucket,+} from './timeline-telemetry.ts';++interface Harness {+ exporter: InMemoryMetricExporter;+ flush: () => Promise<void>;+ cleanup: () => Promise<void>;+}++function setupHarness(): Harness {+ const exporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);+ const reader = new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 60_000 });+ const provider = new MeterProvider({ readers: [reader] });+ metrics.setGlobalMeterProvider(provider);+ __resetTimelineTelemetryForTesting();+ __resetMaintenanceTelemetryForTesting();+ return {+ exporter,+ flush: () => reader.forceFlush(),+ async cleanup() {+ await provider.shutdown();+ metrics.disable();+ __resetTimelineTelemetryForTesting();+ __resetMaintenanceTelemetryForTesting();+ },+ };+}++interface Point {+ attributes: Record<string, unknown>;+ count?: number;+ value?: number;+}++function points(h: Harness, name: string): Point[] {+ const out: Point[] = [];+ for (const rm of h.exporter.getMetrics()) {+ for (const sm of rm.scopeMetrics) {+ for (const metric of sm.metrics) {+ if (metric.descriptor.name !== name) continue;+ for (const dp of metric.dataPoints) {+ const v = dp.value as unknown;+ if (v && typeof v === 'object' && 'count' in (v as Record<string, unknown>)) {+ out.push({ attributes: dp.attributes, count: (v as { count: number }).count });+ } else {+ out.push({ attributes: dp.attributes, value: v as number });+ }+ }+ }+ }+ }+ return out;+}++describe('bucketing is bounded-cardinality (cardinality STOP rule)', () => {+ test('widthBucket maps any width to one of a fixed enum', () => {+ const seen = new Set<string>();+ for (const n of [-5, 0, 1, 3, 12, 30, 57, 1000, 100_000]) seen.add(widthBucket(n));+ for (const b of seen) expect(['0', '1', '2-5', '6-20', '21-50', '50+']).toContain(b);+ expect(seen.size).toBeLessThanOrEqual(6);+ });++ test('commitsBucket maps any commit count to one of a fixed enum', () => {+ const seen = new Set<string>();+ for (const n of [-1, 0, 50, 51, 200, 500, 501, 1_000_000]) seen.add(commitsBucket(n));+ for (const b of seen) expect(['0', '1-50', '51-200', '201-500', '500+']).toContain(b);+ expect(seen.size).toBeLessThanOrEqual(5);+ });+});++describe('FR9 telemetry completeness — every instrument emits with bounded attributes', () => {+ let h: Harness;+ beforeEach(() => {+ h = setupHarness();+ });+ afterEach(async () => {+ await h.cleanup();+ });++ test('all FR9 instruments emit, and no data point carries an unbounded attribute', async () => {+ recordTimelineQuery({ durationMs: 31_000, width: 57, commits: 600, capped: true });+ recordTimelineCoalesced('doc');+ recordTimelineCoalesced('folder');+ recordMaintenanceRun('gc', 'ok', 1234);+ recordMaintenanceRun('consolidation', 'ok', 50);+ recordMaintenanceRun('reap', 'ok', 80);+ recordGcLatch();+ recordConsolidation('dead-chain');+ await h.flush();++ expect(points(h, 'ok.timeline.query_duration_ms').length).toBeGreaterThan(0);+ expect(points(h, 'ok.timeline.coalesced_total').length).toBeGreaterThan(0);+ expect(points(h, 'ok.shadow.maintenance.run_duration_ms').length).toBeGreaterThan(0);+ expect(points(h, 'ok.shadow.maintenance.gc_latch_total').length).toBeGreaterThan(0);+ expect(points(h, 'ok.shadow.maintenance.consolidation_total').length).toBeGreaterThan(0);++ const allowed: Record<string, Set<string>> = {+ width_bucket: new Set(['0', '1', '2-5', '6-20', '21-50', '50+']),+ commits_bucket: new Set(['0', '1-50', '51-200', '201-500', '500+']),+ capped: new Set(['true', 'false']),+ error: new Set(['true', 'false']),+ mode: new Set(['doc', 'folder']),+ op: new Set(['gc', 'consolidation', 'reap']),+ outcome: new Set(['ok', 'skipped', 'error']),+ trigger: new Set(['dead-chain', 'session-close', 'boot', 'ttl']),+ };+ for (const name of [+ 'ok.timeline.query_duration_ms',+ 'ok.timeline.coalesced_total',+ 'ok.shadow.maintenance.run_duration_ms',+ 'ok.shadow.maintenance.gc_latch_total',+ 'ok.shadow.maintenance.consolidation_total',+ ]) {+ for (const p of points(h, name)) {+ for (const [k, v] of Object.entries(p.attributes)) {+ expect(allowed[k]).toBeDefined(); // only known, bounded keys+ expect(allowed[k]?.has(String(v))).toBe(true); // only known, bounded values+ }+ }+ }+ });+});++describe('PRD-6972 incident replay — storyline from telemetry + diagnose readers alone', () => {+ let h: Harness;+ let tmpDir: string;+ let shadow: ShadowHandle;++ beforeEach(async () => {+ h = setupHarness();+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-replay-'));+ const projectRoot = resolve(tmpDir, 'project');+ const contentDir = resolve(projectRoot, 'content/docs');+ mkdirSync(contentDir, { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'T');+ await git.raw('config', 'user.email', 't@t');+ writeFileSync(resolve(contentDir, 'intro.md'), '# h\n');+ await git.add('.');+ await git.commit('init');+ shadow = await initShadowRepo(projectRoot);+ for (let i = 0; i < 8; i++) {+ writeFileSync(resolve(contentDir, 'intro.md'), `# v${i}\n`);+ await commitWip(+ shadow,+ { id: `agent-${randomUUID()}`, name: 'a', email: 'a@x' },+ 'content/docs',+ `wip ${i}`,+ );+ }+ writeFileSync(resolve(shadow.gitDir, 'gc.log'), 'warning: prior gc failed\n');+ });++ afterEach(async () => {+ await h.cleanup();+ await rm(tmpDir, { recursive: true, force: true });+ });++ test('the incident is reconstructable without a bundle', async () => {+ const width = await countWipRefs(shadow);+ const objects = await countShadowObjects(shadow);+ const latch = hasGcLogLatch(shadow);+ expect(width).toBeGreaterThanOrEqual(8); // version-journal width+ expect(objects.looseObjects).toBeGreaterThan(0); // unpacked accumulation+ expect(latch).toBe(true); // auto-gc disabled++ recordTimelineQuery({ durationMs: 30_000, width, commits: 600, capped: true }); // bounded/slow walk+ recordTimelineQuery({ durationMs: 30_000, width: 0, commits: 0, capped: false, error: true });+ recordTimelineCoalesced('doc'); // a poll-storm request coalesced+ recordTimelineCoalesced('doc');+ recordMaintenanceRun('gc', 'ok', 100);+ recordGcLatch(); // the latch was observed during maintenance+ await h.flush();++ const query = points(h, 'ok.timeline.query_duration_ms');+ const coalesced = points(h, 'ok.timeline.coalesced_total');+ const gcLatch = points(h, 'ok.shadow.maintenance.gc_latch_total');++ const reconstruction = {+ walkSaturated: query.some((p) => String(p.attributes.capped) === 'true'),+ wideJournalSignal: query.some((p) => p.attributes.width_bucket === widthBucket(width)),+ timeoutStormSignal: query.some(+ (p) =>+ String(p.attributes.error) === 'true' &&+ p.attributes.width_bucket === '0' &&+ p.attributes.commits_bucket === '0',+ ),+ pollStormCoalesced: coalesced.reduce((n, p) => n + (p.value ?? 0), 0) >= 2,+ gcLatchObserved: gcLatch.reduce((n, p) => n + (p.value ?? 0), 0) >= 1,+ refWidth: width,+ looseObjects: objects.looseObjects,+ latchPresent: latch,+ };++ expect(reconstruction.walkSaturated).toBe(true);+ expect(reconstruction.wideJournalSignal).toBe(true);+ expect(reconstruction.timeoutStormSignal).toBe(true);+ expect(reconstruction.pollStormCoalesced).toBe(true);+ expect(reconstruction.gcLatchObserved).toBe(true);+ expect(reconstruction.refWidth).toBeGreaterThanOrEqual(8);+ expect(reconstruction.latchPresent).toBe(true);+ });+});++describe('gc.log latch counter measures distinct episodes, not observations', () => {+ let h: Harness;+ let tmpDir: string;+ let shadow: ShadowHandle;+ const gcLogPath = (): string => resolve(shadow.gitDir, 'gc.log');+ const gcLatchTotal = (): number =>+ points(h, 'ok.shadow.maintenance.gc_latch_total').reduce((n, p) => n + (p.value ?? 0), 0);++ beforeEach(async () => {+ h = setupHarness();+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-latch-'));+ const projectRoot = resolve(tmpDir, 'project');+ mkdirSync(projectRoot, { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'T');+ await git.raw('config', 'user.email', 't@t');+ writeFileSync(resolve(projectRoot, 'r.md'), '# h\n');+ await git.add('.');+ await git.commit('init');+ shadow = await initShadowRepo(projectRoot);+ });++ afterEach(async () => {+ await h.cleanup();+ await rm(tmpDir, { recursive: true, force: true });+ });++ test('a persistent latch counts once across repeated observations', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });++ writeFileSync(gcLogPath(), 'warning: prior gc failed\n');+ await coord.runGc('a');+ await coord.runGc('b');+ await coord.runGc('c');+ await h.flush();+ expect(hasGcLogLatch(shadow)).toBe(true); // the latch genuinely persisted+ expect(gcLatchTotal()).toBe(1);+ }, 30_000);+});diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex 3a743d94c..6fa98154c 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -406,6 +406,13 @@ export {type TimelineRescueEntry,type WriterIdentity,} from './shadow-repo.ts';+export {+ countShadowObjects,+ countStaleAgentWipRefs,+ countWipRefs,+ hasGcLogLatch,+ type ShadowObjectStats,+} from './shadow-repo-stats.ts';export {createEphemeralProjectDir,prepareSingleFileOpen,diff --git a/packages/server/src/maintenance-consolidation.test.ts b/packages/server/src/maintenance-consolidation.test.tsnew file mode 100644index 000000000..5830ca93e--- /dev/null+++ b/packages/server/src/maintenance-consolidation.test.ts@@ -0,0 +1,253 @@+import { beforeEach, describe, expect, test } from 'bun:test';+import { mkdirSync, writeFileSync } from 'node:fs';+import { mkdtemp } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { parseCheckpoint } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import simpleGit from 'simple-git';+import { createMaintenanceCoordinator } from './maintenance-coordinator.ts';+import { commitWip, initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';+import { getDocumentHistory } from './timeline-query.ts';++let tmpDir: string;+let projectRoot: string;+let contentDir: string;+let shadow: ShadowHandle;+let liveWriters: Set<string>;++beforeEach(async () => {+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-consolidate-test-'));+ projectRoot = resolve(tmpDir, 'project');+ contentDir = resolve(projectRoot, 'content/docs');+ mkdirSync(contentDir, { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');+ await git.add('.');+ await git.commit('Initial commit');+ shadow = await initShadowRepo(projectRoot);+ liveWriters = new Set();+});++function makeCoordinator() {+ return createMaintenanceCoordinator({+ getShadow: () => shadow,+ getCurrentBranch: () => 'main',+ contentRoot: 'content/docs',+ isWriterLive: (w) => liveWriters.has(w),+ });+}++async function commitAs(writerId: string, content: string) {+ writeFileSync(resolve(contentDir, 'intro.md'), content);+ await commitWip(+ shadow,+ { id: writerId, name: writerId, email: `${writerId}@openknowledge.local` },+ 'content/docs',+ `wip: ${writerId}`,+ );+}++async function wipRefNames(): Promise<string[]> {+ const sg = shadowGit(shadow);+ try {+ return (await sg.raw('for-each-ref', '--format=%(refname)', 'refs/wip/main/'))+ .trim()+ .split('\n')+ .filter(Boolean);+ } catch {+ return [];+ }+}++async function latestCheckpointKind(): Promise<string | null> {+ const sg = shadowGit(shadow);+ const shas = (+ await sg.raw(+ 'for-each-ref',+ '--sort=-creatordate',+ '--format=%(objectname)',+ 'refs/checkpoints/main/',+ )+ )+ .trim()+ .split('\n')+ .filter(Boolean);+ if (!shas[0]) return null;+ const body = (await sg.raw('log', '-1', '--format=%B', shas[0])).trim();+ return parseCheckpoint(body)?.kind ?? null;+}++describe('auto-consolidation (PRD-6972 FR5 / D9 / D10 / D20)', () => {+ test('8 live agents writing → zero consolidations (below dead-chain threshold)', async () => {+ for (let i = 1; i <= 8; i++) {+ await commitAs(`agent-${i}`, `# edit ${i}\n`);+ liveWriters.add(`agent-${i}`); // all live+ }+ const result = await makeCoordinator().consolidateDeadChains('flush-counter');+ expect(result.consolidated).toBe(false);+ expect(result.skipped).toBe('below-threshold');+ expect(result.deadChains).toBe(0);+ });++ test('sessions end → exactly one consolidation folds the dead chains', async () => {+ for (let i = 1; i <= 8; i++) await commitAs(`agent-${i}`, `# edit ${i}\n`);+ const result = await makeCoordinator().consolidateDeadChains('session-close');+ expect(result.consolidated).toBe(true);+ expect(result.deadChains).toBe(8);+ expect(result.widthAfter ?? 99).toBeLessThan(result.widthBefore ?? 0);++ const refs = await wipRefNames();+ expect(refs.filter((r) => r.includes('/agent-'))).toHaveLength(0);+ expect(await latestCheckpointKind()).toBe('auto-consolidation');+ });++ test('losslessness is provable at the git-DAG layer: pre-fold tips are reachable from the checkpoint', async () => {+ const sg = shadowGit(shadow);+ const preFoldTips: string[] = [];+ for (let i = 1; i <= 8; i++) {+ await commitAs(`agent-${i}`, `# edit ${i}\n`);+ preFoldTips.push((await sg.raw('rev-parse', `refs/wip/main/agent-${i}`)).trim());+ }++ const result = await makeCoordinator().consolidateDeadChains('session-close');+ expect(result.consolidated).toBe(true);+ expect(result.deadChains).toBe(8);++ const checkpointSha = (+ await sg.raw(+ 'for-each-ref',+ '--sort=-creatordate',+ '--count=1',+ '--format=%(objectname)',+ 'refs/checkpoints/main/',+ )+ ).trim();+ const reachable = new Set(+ (await sg.raw('rev-list', checkpointSha)).trim().split('\n').filter(Boolean),+ );+ for (const tip of preFoldTips) {+ expect(reachable.has(tip)).toBe(true);+ }++ const fsck = await sg.raw('fsck', '--full', '--connectivity-only');+ expect(fsck).not.toContain('missing');+ expect(fsck).not.toContain('broken');+ });++ test('D20: only dead AGENT chains count — principal- / classified chains survive', async () => {+ for (let i = 1; i <= 5; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ await commitAs('principal-11111111-1111-1111-1111-111111111111', '# p\n');+ await commitAs('file-system', '# fs\n');+ const result = await makeCoordinator().consolidateDeadChains('flush-counter');+ expect(result.consolidated).toBe(true);+ expect(result.deadChains).toBe(5); // only the 5 agents++ const refs = await wipRefNames();+ expect(refs.some((r) => r.endsWith('/principal-11111111-1111-1111-1111-111111111111'))).toBe(+ true,+ );+ expect(refs.some((r) => r.endsWith('/file-system'))).toBe(true);+ expect(refs.filter((r) => r.includes('/agent-'))).toHaveLength(0);+ });++ test('park-tipped agent refs are never folded', async () => {+ for (let i = 1; i <= 5; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ const sg = shadowGit(shadow);+ const tree = (await sg.raw('log', '-1', '--format=%T', 'refs/wip/main/agent-1')).trim();+ const parkSha = (+ await sg+ .env({+ GIT_DIR: shadow.gitDir,+ GIT_AUTHOR_NAME: 'svc',+ GIT_AUTHOR_EMAIL: 'svc@x',+ GIT_COMMITTER_NAME: 'svc',+ GIT_COMMITTER_EMAIL: 'svc@x',+ })+ .raw('commit-tree', tree, '-m', 'park: switching branch')+ ).trim();+ await sg.raw('update-ref', 'refs/wip/main/agent-parked', parkSha);++ const result = await makeCoordinator().consolidateDeadChains('flush-counter');+ expect(result.consolidated).toBe(true);+ expect(result.deadChains).toBe(5); // parked one excluded++ const refs = await wipRefNames();+ expect(refs.some((r) => r.endsWith('/agent-parked'))).toBe(true); // park ref survives+ });++ test('live chains are never touched while dead chains are folded (no orphan)', async () => {+ for (let i = 1; i <= 5; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ await commitAs('agent-live', '# live edit\n');+ liveWriters.add('agent-live'); // this one is live++ const result = await makeCoordinator().consolidateDeadChains('flush-counter');+ expect(result.consolidated).toBe(true);+ expect(result.deadChains).toBe(5);++ const refs = await wipRefNames();+ expect(refs.some((r) => r.endsWith('/agent-live'))).toBe(true);+ });++ test('respects ≥10min spacing — a second immediate run is skipped', async () => {+ for (let i = 1; i <= 6; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ const coord = makeCoordinator();+ const first = await coord.consolidateDeadChains('flush-counter');+ expect(first.consolidated).toBe(true);+ for (let i = 7; i <= 12; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ const second = await coord.consolidateDeadChains('flush-counter');+ expect(second.consolidated).toBe(false);+ expect(second.skipped).toBe('spacing');+ });++ test('no-ops when consolidation deps are not configured', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ for (let i = 1; i <= 6; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ const result = await coord.consolidateDeadChains('flush-counter');+ expect(result.consolidated).toBe(false);+ expect(result.skipped).toBe('unconfigured');+ });++ test('a failed fold does NOT consume the spacing window (retries on the next trigger)', async () => {+ for (let i = 1; i <= 5; i++) await commitAs(`agent-${i}`, `# a${i}\n`);+ const coord = createMaintenanceCoordinator({+ getShadow: () => shadow,+ getCurrentBranch: () => 'main',+ contentRoot: 'no-such-content-dir-xyz', // breaks saveVersion's `git add`+ isWriterLive: (w) => liveWriters.has(w),+ });+ const first = await coord.consolidateDeadChains('flush-counter');+ expect(first.consolidated).toBe(false);+ expect(first.skipped).toBe('error');+ const second = await coord.consolidateDeadChains('flush-counter');+ expect(second.skipped).toBe('error');+ expect(second.skipped).not.toBe('spacing');+ });+});++describe('D16 timeline exclusion of auto-consolidation checkpoints', () => {+ test('WIP rows survive a consolidation with no new visible checkpoint row', async () => {+ for (let i = 1; i <= 5; i++) await commitAs(`agent-${i}`, `# edit ${i}\n`);++ const before = await getDocumentHistory(shadow, { docName: 'intro' }, 'content/docs');+ const beforeWipShas = new Set(before.entries.filter((e) => e.type === 'wip').map((e) => e.sha));+ expect(beforeWipShas.size).toBeGreaterThan(0);++ const result = await makeCoordinator().consolidateDeadChains('flush-counter');+ expect(result.consolidated).toBe(true);++ const after = await getDocumentHistory(shadow, { docName: 'intro' }, 'content/docs');+ expect(after.entries.some((e) => e.checkpoint?.kind === 'auto-consolidation')).toBe(false);+ const afterWipShas = new Set(after.entries.filter((e) => e.type === 'wip').map((e) => e.sha));+ for (const sha of beforeWipShas) expect(afterWipShas.has(sha)).toBe(true);++ const withAuto = await getDocumentHistory(+ shadow,+ { docName: 'intro', includeAutoCheckpoints: true },+ 'content/docs',+ );+ expect(withAuto.entries.some((e) => e.checkpoint?.kind === 'auto-consolidation')).toBe(true);+ });+});diff --git a/packages/server/src/maintenance-coordinator.test.ts b/packages/server/src/maintenance-coordinator.test.tsnew file mode 100644index 000000000..97c54e349--- /dev/null+++ b/packages/server/src/maintenance-coordinator.test.ts@@ -0,0 +1,247 @@+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import simpleGit from 'simple-git';+import {+ createMaintenanceCoordinator,+ FLUSH_GC_INTERVAL,+ type MaintenanceCoordinator,+} from './maintenance-coordinator.ts';+import {+ commitWip,+ configureShadowGc,+ initShadowRepo,+ type ShadowHandle,+ shadowGit,+ type WriterIdentity,+} from './shadow-repo.ts';+import { countShadowObjects } from './shadow-repo-stats.ts';++let tmpDir: string;+let projectRoot: string;+let contentDir: string;+let shadow: ShadowHandle;++const human: WriterIdentity = { id: 'human-ada', name: 'Ada', email: '[email protected]' };++beforeEach(async () => {+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-maint-test-'));+ projectRoot = resolve(tmpDir, 'project');+ contentDir = resolve(projectRoot, 'content/docs');+ mkdirSync(contentDir, { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');+ await git.add('.');+ await git.commit('Initial commit');+ shadow = await initShadowRepo(projectRoot);+});++afterEach(async () => {+ await rm(tmpDir, { recursive: true, force: true });+});++async function seedReachableLooseObjects(n: number): Promise<void> {+ const sg = shadowGit(shadow);+ for (let i = 0; i < n; i++) {+ writeFileSync(resolve(contentDir, `f${i}.md`), `# file ${i} ${randomUUID()}\n`);+ }+ const idx = resolve(shadow.gitDir, `index-seed-${randomUUID()}`);+ await sg+ .env({ GIT_DIR: shadow.gitDir, GIT_WORK_TREE: shadow.workTree, GIT_INDEX_FILE: idx })+ .raw('add', 'content/docs');+ const tree = (+ await sg.env({ GIT_DIR: shadow.gitDir, GIT_INDEX_FILE: idx }).raw('write-tree')+ ).trim();+ const sha = (+ await sg+ .env({+ GIT_DIR: shadow.gitDir,+ GIT_AUTHOR_NAME: 'Ada',+ GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_COMMITTER_NAME: 'Ada',+ GIT_COMMITTER_EMAIL: '[email protected]',+ })+ .raw('commit-tree', tree, '-m', 'wip: seed')+ ).trim();+ await sg.raw('update-ref', 'refs/wip/main/human-ada', sha);+ rmSync(idx, { force: true });+}++type WithScheduledMaintenance = { runScheduledMaintenance(trigger: string): Promise<void> };+function spyScheduledMaintenance(coord: MaintenanceCoordinator) {+ return spyOn(coord as unknown as WithScheduledMaintenance, 'runScheduledMaintenance');+}++describe('configureShadowGc (PRD-6972 D8)', () => {+ test('writes gc.auto / autoDetach / commit-graph config (idempotent)', async () => {+ await configureShadowGc(shadow); // initShadowRepo already ran it; idempotent re-run+ const sg = shadowGit(shadow);+ expect((await sg.raw('config', 'gc.auto')).trim()).toBe('512');+ expect((await sg.raw('config', 'gc.autoDetach')).trim()).toBe('false');+ expect((await sg.raw('config', 'gc.writeCommitGraph')).trim()).toBe('true');+ expect((await sg.raw('config', 'commitGraph.changedPaths')).trim()).toBe('true');+ });+});++describe('MaintenanceCoordinator.runGc (PRD-6972 FR4)', () => {+ test('packs a >512-loose-object repo: loose drops, packfile appears', async () => {+ await seedReachableLooseObjects(1500); // well over the gc.auto=512 estimate+ const before = await countShadowObjects(shadow);+ expect(before.looseObjects).toBeGreaterThan(512);+ expect(before.packfiles).toBe(0);++ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const result = await coord.runGc('test');++ expect(result.ran).toBe(true);+ expect(result.looseAfter).toBeLessThan(result.looseBefore ?? 0);+ expect(result.packfilesAfter).toBeGreaterThan(0);+ const after = await countShadowObjects(shadow);+ expect(after.looseObjects).toBeLessThan(before.looseObjects);+ }, 60_000);++ test('A1: gc is safe against the shadow layout with a concurrent commit', async () => {+ await seedReachableLooseObjects(1500);+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });++ writeFileSync(resolve(contentDir, 'intro.md'), '# concurrent edit\n');+ const [gcResult, concurrentSha] = await Promise.all([+ coord.runGc('test'),+ commitWip(shadow, human, 'content/docs', 'WIP: during gc'),+ ]);++ expect(gcResult.ran).toBe(true);++ const sg = shadowGit(shadow);+ const fsck = await sg.raw('fsck', '--full', '--strict');+ expect(fsck).not.toContain('error');+ expect(fsck).not.toContain('missing');++ const head = (await sg.raw('rev-parse', 'refs/wip/main/human-ada')).trim();+ expect(head).toBe(concurrentSha);+ }, 60_000);++ test('detects + surfaces a gc.log latch', async () => {+ writeFileSync(resolve(shadow.gitDir, 'gc.log'), 'warning: prior gc failed\n');+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const result = await coord.runGc('test');+ expect(result.ran).toBe(true);+ expect(result.latch).toBe(true);+ });++ test('master kill switch disables maintenance (D18)', async () => {+ const prev = process.env.OK_SHADOW_MAINTENANCE_DISABLED;+ process.env.OK_SHADOW_MAINTENANCE_DISABLED = '1';+ try {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const result = await coord.runGc('test');+ expect(result.ran).toBe(false);+ expect(result.skipped).toBe('disabled');+ } finally {+ if (prev === undefined) delete process.env.OK_SHADOW_MAINTENANCE_DISABLED;+ else process.env.OK_SHADOW_MAINTENANCE_DISABLED = prev;+ }+ });++ test('gate: a second concurrent runGc is skipped as busy (one op at a time)', async () => {+ await seedReachableLooseObjects(1500);+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const [a, b] = await Promise.all([coord.runGc('a'), coord.runGc('b')]);+ const ran = [a, b].filter((r) => r.ran);+ const busy = [a, b].filter((r) => r.skipped === 'busy');+ expect(ran).toHaveLength(1);+ expect(busy).toHaveLength(1);+ }, 60_000);++ test('no-ops gracefully when no shadow repo exists', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => null });+ const result = await coord.runGc('test');+ expect(result.ran).toBe(false);+ expect(result.skipped).toBe('no-shadow');+ });+});++describe('MaintenanceCoordinator triggers (PRD-6972 FR4 / D8 / D12)', () => {+ test('noteFlushCommit fires gc every FLUSH_GC_INTERVAL commits, then resets', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const spy = spyScheduledMaintenance(coord).mockResolvedValue(undefined);+ const drain = () => new Promise((r) => setTimeout(r, 0));++ for (let i = 0; i < FLUSH_GC_INTERVAL - 1; i++) coord.noteFlushCommit();+ await drain();+ expect(spy).toHaveBeenCalledTimes(0);+ coord.noteFlushCommit(); // the FLUSH_GC_INTERVAL-th+ await drain();+ expect(spy).toHaveBeenCalledTimes(1);++ for (let i = 0; i < FLUSH_GC_INTERVAL - 1; i++) coord.noteFlushCommit();+ await drain();+ expect(spy).toHaveBeenCalledTimes(1);+ coord.noteFlushCommit();+ await drain();+ expect(spy).toHaveBeenCalledTimes(2);+ });++ test('noteFlushCommit no-ops when maintenance is disabled', () => {+ const prev = process.env.OK_SHADOW_MAINTENANCE_DISABLED;+ process.env.OK_SHADOW_MAINTENANCE_DISABLED = '1';+ try {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const spy = spyScheduledMaintenance(coord);+ for (let i = 0; i < FLUSH_GC_INTERVAL + 5; i++) coord.noteFlushCommit();+ expect(spy).toHaveBeenCalledTimes(0);+ } finally {+ if (prev === undefined) delete process.env.OK_SHADOW_MAINTENANCE_DISABLED;+ else process.env.OK_SHADOW_MAINTENANCE_DISABLED = prev;+ }+ });++ test('onSessionClose evaluates maintenance', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const spy = spyScheduledMaintenance(coord).mockResolvedValue(undefined);+ await coord.onSessionClose();+ expect(spy).toHaveBeenCalledTimes(1);+ });++ test('runReap no-ops when projectGitDir is not configured', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ await coord.runReap('test');+ expect(coord.isRunning).toBe(false);+ });++ test('runBootMaintenance returns within the cap when gc is slow (background continuation)', async () => {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ let resolveMaintenance: () => void = () => {};+ spyScheduledMaintenance(coord).mockImplementation(+ () =>+ new Promise<void>((res) => {+ resolveMaintenance = () => res();+ }),+ );+ const start = performance.now();+ await coord.runBootMaintenance(50); // 50ms cap+ const elapsed = performance.now() - start;+ expect(elapsed).toBeLessThan(2000);+ resolveMaintenance(); // let the background run settle so it does not dangle+ });++ test('runBootMaintenance no-ops when maintenance is disabled', async () => {+ const prev = process.env.OK_SHADOW_MAINTENANCE_DISABLED;+ process.env.OK_SHADOW_MAINTENANCE_DISABLED = '1';+ try {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ const spy = spyScheduledMaintenance(coord);+ await coord.runBootMaintenance(50);+ expect(spy).toHaveBeenCalledTimes(0);+ } finally {+ if (prev === undefined) delete process.env.OK_SHADOW_MAINTENANCE_DISABLED;+ else process.env.OK_SHADOW_MAINTENANCE_DISABLED = prev;+ }+ });+});diff --git a/packages/server/src/maintenance-coordinator.ts b/packages/server/src/maintenance-coordinator.tsnew file mode 100644index 000000000..91d37d2ea--- /dev/null+++ b/packages/server/src/maintenance-coordinator.ts@@ -0,0 +1,310 @@+import { getLogger } from './logger.ts';+import { gcShadowBranches } from './shadow-branch-gc.ts';+import {+ type ConsolidationTriggerLabel,+ recordConsolidation,+ recordGcLatch,+ recordMaintenanceRun,+} from './shadow-maintenance-telemetry.ts';+import type { ShadowHandle, WriterIdentity } from './shadow-repo.ts';+import {+ enumerateWipChains,+ MAINTENANCE_GIT_TIMEOUT_MS,+ saveVersion,+ shadowGit,+} from './shadow-repo.ts';+import { countShadowObjects, countWipRefs, hasGcLogLatch } from './shadow-repo-stats.ts';++const log = getLogger('shadow-maintenance');++const DEAD_CHAIN_THRESHOLD = (() => {+ const raw = process.env.OK_SHADOW_MAINTENANCE_DEAD_CHAIN_THRESHOLD;+ if (!raw) return 5;+ const parsed = Number.parseInt(raw, 10);+ return Number.isFinite(parsed) && parsed > 0 ? parsed : 5;+})();++const CONSOLIDATION_MIN_SPACING_MS = (() => {+ const raw = process.env.OK_SHADOW_MAINTENANCE_CONSOLIDATION_SPACING_MS;+ if (!raw) return 10 * 60 * 1000;+ const parsed = Number.parseInt(raw, 10);+ return Number.isFinite(parsed) && parsed > 0 ? parsed : 10 * 60 * 1000;+})();++function isMaintenanceDisabled(): boolean {+ return process.env.OK_SHADOW_MAINTENANCE_DISABLED === '1';+}++function consolidationTriggerLabel(trigger: string): ConsolidationTriggerLabel {+ if (trigger === 'boot') return 'boot';+ if (trigger === 'session-close') return 'session-close';+ if (trigger === 'ttl') return 'ttl';+ return 'dead-chain'; // flush-counter and any other → the dead-chain check+}++type GcSkipReason = 'disabled' | 'busy' | 'no-shadow' | 'error';++export interface GcRunResult {+ /** True only when `git gc --auto` actually executed (regardless of whether it+ * decided to pack — under the gc.auto threshold it is a no-op). */+ ran: boolean;+ skipped?: GcSkipReason;+ looseBefore?: number;+ looseAfter?: number;+ packfilesAfter?: number;+ latch?: boolean;+ durationMs?: number;+}++export interface MaintenanceCoordinatorDeps {+ getShadow: () => ShadowHandle | null;+ getCurrentBranch?: () => string | null;+ contentRoot?: string;+ isWriterLive?: (writerId: string) => boolean;+ projectGitDir?: string;+}++export const FLUSH_GC_INTERVAL = 200;++type ConsolidationSkipReason =+ | 'disabled'+ | 'unconfigured'+ | 'busy'+ | 'no-shadow'+ | 'spacing'+ | 'below-threshold'+ | 'error';++export interface ConsolidationResult {+ consolidated: boolean;+ skipped?: ConsolidationSkipReason;+ deadChains?: number;+ widthBefore?: number;+ widthAfter?: number;+}++export class MaintenanceCoordinator {+ private running = false;+ private destroyed = false;+ private flushCommitCounter = 0;+ private lastConsolidationAt = 0;+ private lastGcLatch = false;++ constructor(private readonly deps: MaintenanceCoordinatorDeps) {}++ get isRunning(): boolean {+ return this.running;+ }++ destroy(): void {+ this.destroyed = true;+ }++ noteFlushCommit(): void {+ if (isMaintenanceDisabled() || this.destroyed) return;+ this.flushCommitCounter += 1;+ if (this.flushCommitCounter >= FLUSH_GC_INTERVAL) {+ this.flushCommitCounter = 0;+ void this.runScheduledMaintenance('flush-counter');+ }+ }++ async runBootMaintenance(capMs = 1000): Promise<void> {+ if (isMaintenanceDisabled() || this.destroyed) return;+ const work = this.runScheduledMaintenance('boot');+ let capTimer: ReturnType<typeof setTimeout> | undefined;+ const cap = new Promise<void>((r) => {+ capTimer = setTimeout(r, capMs);+ });+ await Promise.race([work.then(() => undefined), cap]);+ if (capTimer) clearTimeout(capTimer);+ void work.catch((err) => {+ log.warn({ err }, '[shadow-maintenance] boot maintenance background continuation failed');+ });+ }++ async onSessionClose(): Promise<void> {+ await this.runScheduledMaintenance('session-close');+ }++ private async runScheduledMaintenance(trigger: string): Promise<void> {+ if (isMaintenanceDisabled() || this.destroyed) return;+ if (this.running) return;+ this.running = true;+ try {+ await this.consolidateInner(trigger);+ await this.reapInner(trigger);+ await this.gcInner(trigger);+ } finally {+ this.running = false;+ }+ }++ async runReap(trigger: string): Promise<void> {+ if (isMaintenanceDisabled() || this.destroyed) return;+ if (this.running) return;+ this.running = true;+ try {+ await this.reapInner(trigger);+ } finally {+ this.running = false;+ }+ }++ private async reapInner(trigger: string): Promise<void> {+ if (!this.deps.projectGitDir) return; // unconfigured — reap disabled+ const shadow = this.deps.getShadow();+ if (!shadow) return;++ const start = performance.now();+ try {+ await gcShadowBranches(+ shadow,+ this.deps.projectGitDir,+ undefined,+ this.deps.contentRoot ?? '.',+ );+ recordMaintenanceRun('reap', 'ok', performance.now() - start);+ } catch (e) {+ recordMaintenanceRun('reap', 'error', performance.now() - start);+ log.warn({ trigger, err: e }, '[shadow-maintenance] reap failed; retrying next trigger');+ }+ }++ async consolidateDeadChains(trigger: string): Promise<ConsolidationResult> {+ if (isMaintenanceDisabled() || this.destroyed) {+ return { consolidated: false, skipped: 'disabled' };+ }+ if (this.running) return { consolidated: false, skipped: 'busy' };+ this.running = true;+ try {+ return await this.consolidateInner(trigger);+ } finally {+ this.running = false;+ }+ }++ private async consolidateInner(trigger: string): Promise<ConsolidationResult> {+ const { getCurrentBranch, isWriterLive } = this.deps;+ if (!getCurrentBranch || !isWriterLive) {+ return { consolidated: false, skipped: 'unconfigured' };+ }+ if (Date.now() - this.lastConsolidationAt < CONSOLIDATION_MIN_SPACING_MS) {+ return { consolidated: false, skipped: 'spacing' };+ }+ const shadow = this.deps.getShadow();+ if (!shadow) return { consolidated: false, skipped: 'no-shadow' };++ try {+ const branch = getCurrentBranch() ?? 'main';+ const dead = await this.findDeadAgentChains(shadow, branch, isWriterLive);+ if (dead.length < DEAD_CHAIN_THRESHOLD) {+ return { consolidated: false, skipped: 'below-threshold', deadChains: dead.length };+ }+ const widthBefore = await countWipRefs(shadow, branch);+ await saveVersion(shadow, this.deps.contentRoot ?? '', dead, branch, undefined, {+ checkpointKind: {+ foldedRefs: dead.length,+ trigger: consolidationTriggerLabel(trigger),+ },+ timeoutMs: MAINTENANCE_GIT_TIMEOUT_MS,+ });+ this.lastConsolidationAt = Date.now();+ const widthAfter = await countWipRefs(shadow, branch);+ recordConsolidation(consolidationTriggerLabel(trigger));+ log.info(+ { trigger, branch, foldedChains: dead.length, widthBefore, widthAfter },+ '[shadow-maintenance] auto-consolidation folded dead agent chains',+ );+ return { consolidated: true, deadChains: dead.length, widthBefore, widthAfter };+ } catch (e) {+ log.warn(+ { trigger, err: e },+ '[shadow-maintenance] consolidation failed; retrying next trigger',+ );+ return { consolidated: false, skipped: 'error' };+ }+ }++ private async findDeadAgentChains(+ shadow: ShadowHandle,+ branch: string,+ isWriterLive: (writerId: string) => boolean,+ ): Promise<WriterIdentity[]> {+ const chains = await enumerateWipChains(shadow, branch);+ return chains+ .filter((c) => c.classification === 'agent' && !c.isPark && !isWriterLive(c.writerId))+ .map((c) => ({+ id: c.writerId,+ name: c.writerId,+ email: `${c.writerId}@openknowledge.local`,+ }));+ }++ async runGc(trigger: string): Promise<GcRunResult> {+ if (isMaintenanceDisabled()) return { ran: false, skipped: 'disabled' };+ if (this.destroyed) return { ran: false, skipped: 'no-shadow' };+ if (this.running) {+ recordMaintenanceRun('gc', 'skipped', 0);+ return { ran: false, skipped: 'busy' };+ }+ this.running = true;+ try {+ return await this.gcInner(trigger);+ } finally {+ this.running = false;+ }+ }++ private async gcInner(trigger: string): Promise<GcRunResult> {+ const shadow = this.deps.getShadow();+ if (!shadow) return { ran: false, skipped: 'no-shadow' };++ const start = performance.now();+ try {+ const before = await countShadowObjects(shadow);+ const sg = shadowGit(shadow, { timeoutMs: MAINTENANCE_GIT_TIMEOUT_MS });+ await sg.raw('gc', '--auto');+ const after = await countShadowObjects(shadow);+ const latch = hasGcLogLatch(shadow);+ const durationMs = performance.now() - start;+ recordMaintenanceRun('gc', 'ok', durationMs);+ if (latch) {+ if (!this.lastGcLatch) recordGcLatch();+ log.warn(+ { trigger, looseObjects: after.looseObjects },+ '[shadow-maintenance] gc.log latch present — auto-gc disabled until it self-expires (~1 day); retrying next trigger',+ );+ }+ this.lastGcLatch = latch;+ log.info(+ {+ trigger,+ looseBefore: before.looseObjects,+ looseAfter: after.looseObjects,+ packfiles: after.packfiles,+ durationMs: Math.round(durationMs),+ },+ '[shadow-maintenance] gc complete',+ );+ return {+ ran: true,+ looseBefore: before.looseObjects,+ looseAfter: after.looseObjects,+ packfilesAfter: after.packfiles,+ latch,+ durationMs,+ };+ } catch (e) {+ recordMaintenanceRun('gc', 'error', performance.now() - start);+ log.warn({ trigger, err: e }, '[shadow-maintenance] gc failed; retrying next trigger');+ return { ran: false, skipped: 'error' };+ }+ }+}++export function createMaintenanceCoordinator(+ deps: MaintenanceCoordinatorDeps,+): MaintenanceCoordinator {+ return new MaintenanceCoordinator(deps);+}diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.tsindex f10fb76d4..315dea6ea 100644--- a/packages/server/src/mcp-mount.ts+++ b/packages/server/src/mcp-mount.ts@@ -11,6 +11,7 @@ import { isAllowedApiOrigin } from './api-origin.ts';import { errorResponse } from './http/error-response.ts';import type { PinoLogger } from './logger.ts';import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';+import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';import type { McpHttpHandler } from './mcp-http.ts';import { handleCollabSocketError, incrementCollabMessageTooLarge } from './metrics.ts';@@ -31,6 +32,7 @@ export interface MountMcpAndApiOptions {sessionManager?: AgentSessionManager;agentFocusBroadcaster?: AgentFocusBroadcaster | null;agentPresenceBroadcaster?: AgentPresenceBroadcaster | null;+ maintenanceCoordinator?: MaintenanceCoordinator;keepaliveGraceMs?: number;contentAssetMiddleware?: (req: IncomingMessage, res: ServerResponse, next: () => void) => void;reactShellMiddleware?: (req: IncomingMessage, res: ServerResponse, next: () => void) => void;@@ -51,6 +53,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlsessionManager,agentFocusBroadcaster,agentPresenceBroadcaster,+ maintenanceCoordinator,contentAssetMiddleware,reactShellMiddleware,ephemeral,@@ -292,6 +295,11 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl} catch (err) {log.error({ err, connectionId }, '[keepalive] clearPresence failed');}+ try {+ await maintenanceCoordinator?.onSessionClose();+ } catch (err) {+ log.error({ err, connectionId }, '[keepalive] maintenance onSessionClose failed');+ }})();keepaliveGraceInflight.add(work);work.finally(() => keepaliveGraceInflight.delete(work));diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.tsindex 52d345e87..94526a438 100644--- a/packages/server/src/persistence.ts+++ b/packages/server/src/persistence.ts@@ -194,6 +194,7 @@ export interface PersistenceOptions {resolveSize?: (basename: string, sourcePath: string) => number | null;getPrincipal?: () => Principal | null;onAgentCommit?: () => void;+ onFlushCommit?: () => void;onDiskFlush?: (docName: string,sv: Uint8Array,@@ -317,6 +318,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persisconst backlinkIndex = options?.backlinkIndex;const getPrincipal = options?.getPrincipal;const onAgentCommit = options?.onAgentCommit;+ const onFlushCommit = options?.onFlushCommit;const onDiskFlush = options?.onDiskFlush;const mgr = options?.mdManager ?? mdManager;const ephemeral = options?.ephemeral ?? false;@@ -475,6 +477,11 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persistry {const sha = await commitWipFromTree(shadow, writer, treeSha, writerMessage, branch);anySuccess = true;+ try {+ onFlushCommit?.();+ } catch (err) {+ log.warn({ err }, '[persistence] onFlushCommit callback failed (non-fatal)');+ }log.info({ sha: sha.slice(0, 8), writer: writerId, tree: treeSha.slice(0, 8) },`[persistence] Shadow WIP commit: ${sha.slice(0, 8)} on refs/wip/${writerId}`,diff --git a/packages/server/src/save-version.test.ts b/packages/server/src/save-version.test.tsindex 8ef6866ae..73233b519 100644--- a/packages/server/src/save-version.test.ts+++ b/packages/server/src/save-version.test.ts@@ -9,7 +9,14 @@ import simpleGit from 'simple-git';import * as Y from 'yjs';import { AgentSessionManager } from './agent-sessions.ts';import { createApiExtension } from './api-extension.ts';-import { commitWip, initShadowRepo, type ShadowRef, type WriterIdentity } from './shadow-repo.ts';+import {+ commitWip,+ initShadowRepo,+ type ShadowHandle,+ type ShadowRef,+ shadowGit,+ type WriterIdentity,+} from './shadow-repo.ts';interface CapturedResponse {status: number;@@ -302,3 +309,165 @@ describe('PRD-6716: save-version + rollback do not mutate parent git', () => {expect(statusAfter).toBe(statusBefore);});});++describe('PRD-6972 FR6: Save Version unification', () => {+ let tmpDir: string;+ let projectDir: string;+ let contentDir: string;+ let shadow: ShadowHandle;++ beforeEach(async () => {+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-fr6-'));+ projectDir = tmpDir;+ contentDir = join(tmpDir, 'content');+ mkdirSync(contentDir, { recursive: true });+ const git = simpleGit(projectDir);+ await git.init();+ await git.addConfig('user.name', 'Test');+ await git.addConfig('user.email', '[email protected]');+ writeFileSync(join(projectDir, 'README.md'), '# project\n');+ await git.add('.');+ await git.commit('init');+ shadow = await initShadowRepo(projectDir);+ });++ afterEach(() => {+ rmSync(tmpDir, { recursive: true, force: true });+ });++ function makeExt(getCurrentBranch?: () => string | null) {+ const hocuspocus = new Hocuspocus({ quiet: true });+ const sessionManager = new AgentSessionManager(hocuspocus);+ const ext = createApiExtension({+ hocuspocus,+ sessionManager,+ contentDir,+ projectDir,+ shadowRef: { current: shadow } as ShadowRef,+ contentRoot: 'content',+ getFileIndex: () => new Map(),+ ...(getCurrentBranch ? { getCurrentBranch } : {}),+ });+ return { ext, sessionManager };+ }++ async function post(+ ext: ReturnType<typeof makeExt>['ext'],+ body: unknown,+ ): Promise<CapturedResponse> {+ const req = makeJsonPostReq('/api/save-version', body);+ const { res, captured } = makeRes();+ await (+ ext as {+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;+ }+ ).onRequest({ request: req, response: res });+ return captured;+ }++ async function wipRefs(branch: string): Promise<string[]> {+ const sg = shadowGit(shadow);+ return (await sg.raw('for-each-ref', '--format=%(refname)', `refs/wip/${branch}/`))+ .trim()+ .split('\n')+ .filter(Boolean);+ }++ test('empty-body request consolidates ALL non-park WIP chains on the active branch', async () => {+ writeFileSync(join(contentDir, 'doc.md'), '# a\n');+ await commitWip(+ shadow,+ { id: 'agent-1', name: 'a1', email: 'a1@x' },+ 'content',+ 'wip a1',+ 'main',+ );+ writeFileSync(join(contentDir, 'doc.md'), '# b\n');+ await commitWip(+ shadow,+ { id: 'agent-2', name: 'a2', email: 'a2@x' },+ 'content',+ 'wip a2',+ 'main',+ );+ writeFileSync(join(contentDir, 'doc.md'), '# c\n');+ await commitWip(+ shadow,+ { id: 'principal-p', name: 'p', email: 'p@x' },+ 'content',+ 'wip p',+ 'main',+ );+ expect(await wipRefs('main')).toHaveLength(3);++ const { ext, sessionManager } = makeExt();+ try {+ const captured = await post(ext, {});+ expect(captured.status).toBe(200);+ expect(typeof captured.parsed.checkpointRef).toBe('string');+ expect(await wipRefs('main')).toHaveLength(0);+ } finally {+ await sessionManager.closeAll();+ }+ });++ test('explicit writers list stays scoped (does not fold everything)', async () => {+ await commitWip(+ shadow,+ { id: 'agent-1', name: 'a1', email: 'a1@x' },+ 'content',+ 'wip a1',+ 'main',+ );+ await commitWip(+ shadow,+ { id: 'agent-2', name: 'a2', email: 'a2@x' },+ 'content',+ 'wip a2',+ 'main',+ );++ const { ext, sessionManager } = makeExt();+ try {+ const captured = await post(ext, { writers: [{ id: 'agent-1', name: 'a1', email: 'a1@x' }] });+ expect(captured.status).toBe(200);+ const remaining = await wipRefs('main');+ expect(remaining.some((r) => r.endsWith('/agent-1'))).toBe(false);+ expect(remaining.some((r) => r.endsWith('/agent-2'))).toBe(true);+ } finally {+ await sessionManager.closeAll();+ }+ });++ test('threads the active branch (consolidates a feature branch, not main)', async () => {+ await commitWip(+ shadow,+ { id: 'agent-1', name: 'a1', email: 'a1@x' },+ 'content',+ 'wip',+ 'feature-x',+ );+ expect(await wipRefs('feature-x')).toHaveLength(1);++ const { ext, sessionManager } = makeExt(() => 'feature-x');+ try {+ const captured = await post(ext, {});+ expect(captured.status).toBe(200);+ expect(captured.parsed.checkpointRef as string).toContain('refs/checkpoints/feature-x/');+ expect(await wipRefs('feature-x')).toHaveLength(0);+ } finally {+ await sessionManager.closeAll();+ }+ });++ test('empty-body with no WIP activity still lands a checkpoint', async () => {+ const { ext, sessionManager } = makeExt();+ try {+ const captured = await post(ext, {});+ expect(captured.status).toBe(200);+ expect(typeof captured.parsed.checkpointRef).toBe('string');+ } finally {+ await sessionManager.closeAll();+ }+ });+});diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 05a9093a3..8871038c7 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -81,6 +81,10 @@ import { type HeadWatcherHandle, readBranchFromHead, startHeadWatcher } from './import { createLiveDerivedIndexExtension } from './live-derived-index.ts';import { getLogger } from './logger.ts';import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';+import {+ createMaintenanceCoordinator,+ type MaintenanceCoordinator,+} from './maintenance-coordinator.ts';import { recoverPendingManagedRename } from './managed-rename-journal.ts';import { mdManager, schema } from './md-manager.ts';import {@@ -175,6 +179,7 @@ export interface ServerInstance {cc1Broadcaster: CC1Broadcaster;agentFocusBroadcaster: AgentFocusBroadcaster;agentPresenceBroadcaster: AgentPresenceBroadcaster;+ maintenanceCoordinator?: MaintenanceCoordinator;contentFilter: ContentFilter;basenameIndex: BasenameIndex;readonly serverInstanceId: string;@@ -310,6 +315,7 @@ export function createServer(options: ServerOptions): ServerInstance {let backlinkIndex: BacklinkIndex;let tagIndex: TagIndex;let shadowRef: ShadowRef;+ let maintenanceCoordinator: MaintenanceCoordinator | undefined;let persistence: ReturnType<typeof createPersistenceExtension>;let hocuspocus: Hocuspocus;let sessionManager: AgentSessionManager;@@ -441,6 +447,32 @@ export function createServer(options: ServerOptions): ServerInstance {shadowRef = { current: shadowRepo };+ maintenanceCoordinator = gitEnabled+ ? createMaintenanceCoordinator({+ getShadow: () => shadowRef.current ?? null,+ getCurrentBranch: () => headWatcher?.getLastKnownBranch() ?? null,+ contentRoot: contentRoot ?? '',+ projectGitDir: resolveGitDir(projectDir) ?? undefined,+ isWriterLive: (writerId) => {+ if (!agentPresenceBroadcaster && !sessionManager) {+ getLogger('server-factory').debug(+ { writerId },+ '[server-factory] isWriterLive called before liveness deps populated — treating writer as dead',+ );+ return false;+ }+ if (agentPresenceBroadcaster?.getPresenceMap()[writerId]) return true;+ const connId = writerId.startsWith('agent-')+ ? writerId.slice('agent-'.length)+ : writerId;+ for (const _session of sessionManager?.sessionsForConnection(connId) ?? []) {+ return true;+ }+ return false;+ },+ })+ : undefined;+const persistenceOpts: PersistenceOptions = {contentDir,projectDir,@@ -457,6 +489,7 @@ export function createServer(options: ServerOptions): ServerInstance {resolveSize,getPrincipal: () => loadedPrincipal,onAgentCommit: () => cc1Broadcaster?.signal('session-activity'),+ onFlushCommit: () => maintenanceCoordinator?.noteFlushCommit(),onDiskFlush: (docName, sv, persistedMarkdown, previousMarkdown) => {cc1Broadcaster?.emitDiskAck(docName, sv);if (isSystemDoc(docName) || isConfigDoc(docName)) return;@@ -1271,6 +1304,8 @@ export function createServer(options: ServerOptions): ServerInstance {const documentCount = hocuspocus.documents.size;+ maintenanceCoordinator?.destroy();+try {try {try {@@ -1502,6 +1537,12 @@ export function createServer(options: ServerOptions): ServerInstance {log.warn({ err: e }, '[rename-log] boot-time GC/rebuild failed; index loaded without GC');}}++ try {+ await maintenanceCoordinator?.runBootMaintenance();+ } catch (e) {+ log.warn({ err: e }, '[shadow-maintenance] boot maintenance failed (non-fatal)');+ }}if (shadowRef.current) {@@ -2294,6 +2335,7 @@ export function createServer(options: ServerOptions): ServerInstance {cc1Broadcaster,agentFocusBroadcaster,agentPresenceBroadcaster,+ maintenanceCoordinator,contentFilter,basenameIndex,serverInstanceId,diff --git a/packages/server/src/shadow-branch-gc.test.ts b/packages/server/src/shadow-branch-gc.test.tsindex 7339e0246..c580d7cca 100644--- a/packages/server/src/shadow-branch-gc.test.ts+++ b/packages/server/src/shadow-branch-gc.test.ts@@ -3,6 +3,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { resolve } from 'node:path';+import { parseCheckpoint } from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';import { gcShadowBranches } from './shadow-branch-gc';import { commitWip, initShadowRepo, shadowGit, type WriterIdentity } from './shadow-repo';@@ -276,4 +277,58 @@ describe('per-writer 30-day TTL GC on active branches (US-019, D54, FR-18)', ()expect(remaining).toContain(`refs/wip/${activeBranch}/agent-fresh`);expect(remaining).toContain(`refs/wip/${activeBranch}/principal-fresh`);});++ test('FR8/NG3: stale session writers are consolidated losslessly, not bare-deleted', async () => {+ const projectRoot = resolve(tmpDir, 'ttl-lossless');+ mkdirSync(resolve(projectRoot, 'content'), { recursive: true });+ writeFileSync(resolve(projectRoot, 'content', 'readme.md'), '# readme\n');+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ await git.add('.');+ await git.commit('initial');+ await git.raw('branch', '-M', activeBranch);++ const shadow = await initShadowRepo(projectRoot);+ await createRefWithDate(shadow, `refs/wip/${activeBranch}/agent-old`, staleDate);+ const sg = shadowGit(shadow);+ const staleSha = (await sg.raw('rev-parse', `refs/wip/${activeBranch}/agent-old`)).trim();++ const result = await gcShadowBranches(+ shadow,+ resolve(projectRoot, '.git'),+ undefined,+ 'content',+ );+ expect(result.deletedStaleSessionRefs).toBe(1);++ let refGone = false;+ try {+ await sg.raw('rev-parse', `refs/wip/${activeBranch}/agent-old`);+ } catch {+ refGone = true;+ }+ expect(refGone).toBe(true);++ const cpShas = (+ await sg.raw('for-each-ref', '--format=%(objectname)', `refs/checkpoints/${activeBranch}/`)+ )+ .trim()+ .split('\n')+ .filter(Boolean);+ expect(cpShas.length).toBeGreaterThan(0);+ let reachable = false;+ let kind: string | null = null;+ for (const cp of cpShas) {+ const ancestors = (await sg.raw('rev-list', cp)).trim().split('\n');+ if (ancestors.includes(staleSha)) {+ reachable = true;+ kind = parseCheckpoint((await sg.raw('log', '-1', '--format=%B', cp)).trim())?.kind ?? null;+ break;+ }+ }+ expect(reachable).toBe(true);+ expect(kind).toBe('auto-consolidation'); // hidden (D16) + bounded (D21)+ });});diff --git a/packages/server/src/shadow-branch-gc.ts b/packages/server/src/shadow-branch-gc.tsindex a3fc724cf..89eb3a538 100644--- a/packages/server/src/shadow-branch-gc.ts+++ b/packages/server/src/shadow-branch-gc.ts@@ -1,8 +1,18 @@import { parseWriterId } from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';+import { getLogger } from './logger.ts';import { gcRenameLog, getOrLoadRenameLogIndex } from './rename-log.ts';-import type { CheckpointRetentionPolicy, ShadowHandle } from './shadow-repo.ts';-import { DEFAULT_CHECKPOINT_RETENTION, gcCheckpointRefs, shadowGit } from './shadow-repo.ts';+import type { CheckpointRetentionPolicy, ShadowHandle, WriterIdentity } from './shadow-repo.ts';+import {+ DEFAULT_CHECKPOINT_RETENTION,+ enumerateWipChains,+ gcCheckpointRefs,+ MAINTENANCE_GIT_TIMEOUT_MS,+ saveVersion,+ shadowGit,+} from './shadow-repo.ts';++const log = getLogger('shadow-gc');const GC_GRACE_PERIOD_MS = 24 * 60 * 60 * 1000;@@ -18,6 +28,7 @@ interface GcResult {scanned: number;deletedBridgeMergeLoss: number;deletedExternalChangeRescue: number;+ deletedAutoConsolidation: number;retained: number;}>;@@ -60,7 +71,9 @@ async function listProjectBranches(projectGitDir: string): Promise<Set<string>>if (line) branches.add(line);}}- } catch {}+ } catch (err) {+ log.warn({ err }, '[shadow-gc] listProjectBranches failed; treating as no project branches');+ }return branches;}@@ -68,6 +81,7 @@ export async function gcShadowBranches(shadow: ShadowHandle,projectGitDir: string,checkpointRetention: CheckpointRetentionPolicy = DEFAULT_CHECKPOINT_RETENTION,+ contentRoot = '.',): Promise<GcResult> {const result: GcResult = {deletedBranches: [],@@ -77,7 +91,7 @@ export async function gcShadowBranches(deletedStaleSessionRefs: 0,};- const sg = shadowGit(shadow);+ const sg = shadowGit(shadow, { timeoutMs: MAINTENANCE_GIT_TIMEOUT_MS });let wipRefsRaw: string;try {@@ -137,8 +151,8 @@ export async function gcShadowBranches(const sha = (await sg.raw('rev-parse', oldRef)).trim();await sg.raw('update-ref', newRef, sha);await sg.raw('update-ref', '-d', oldRef);- } catch (e) {- console.error(`[shadow-gc] failed to migrate ${oldRef} → ${newRef}:`, e);+ } catch (err) {+ log.error({ err, oldRef, newRef }, '[shadow-gc] failed to migrate WIP ref');}}result.renamedBranches.push({ from: orphanedBranch, to: newBranch });@@ -180,56 +194,68 @@ export async function gcShadowBranches(if (ckResult.scanned > 0 ||ckResult.deletedBridgeMergeLoss > 0 ||- ckResult.deletedExternalChangeRescue > 0+ ckResult.deletedExternalChangeRescue > 0 ||+ ckResult.deletedAutoConsolidation > 0) {result.checkpointGc[branch] = {scanned: ckResult.scanned,deletedBridgeMergeLoss: ckResult.deletedBridgeMergeLoss,deletedExternalChangeRescue: ckResult.deletedExternalChangeRescue,+ deletedAutoConsolidation: ckResult.deletedAutoConsolidation,retained: ckResult.retained,};}} catch (err) {- console.warn(`[shadow-gc] checkpoint GC failed for branch ${branch}:`, err);+ log.warn({ err, branch }, '[shadow-gc] checkpoint GC failed');}}try {await gcRenameLog(shadow, getOrLoadRenameLogIndex(shadow.gitDir));} catch (err) {- console.warn('[shadow-gc] rename-log GC failed:', err);+ log.warn({ err }, '[shadow-gc] rename-log GC failed');}+ const now = Date.now();for (const branch of projectBranches) {- const branchPrefix = `refs/wip/${branch}/`;- const branchRefs = wipRefs.filter((r) => r.startsWith(branchPrefix));- for (const ref of branchRefs) {- const writerId = ref.slice(branchPrefix.length);- const { classification } = parseWriterId(writerId);-+ const chains = await enumerateWipChains(shadow, branch);+ const aged: WriterIdentity[] = [];+ for (const c of chains) {if (- classification === 'classified-file-system' ||- classification === 'classified-git-upstream' ||- classification === 'classified-openknowledge-service'+ c.classification === 'classified-file-system' ||+ c.classification === 'classified-git-upstream' ||+ c.classification === 'classified-openknowledge-service') {continue;}-- if (classification === 'unknown') {- console.warn(`[shadow-gc] unknown writer id in active branch ref ${ref} — preserved`);+ if (c.classification === 'unknown') {+ log.warn(+ { branch, writerId: c.writerId },+ '[shadow-gc] unknown writer id in active branch ref — preserved',+ );continue;}-- if (classification === 'agent' || classification === 'principal') {- try {- const commitDate = (await sg.raw('log', '-1', '--format=%ci', ref)).trim();- if (!commitDate) continue;- const age = Date.now() - new Date(commitDate).getTime();- if (age >= SESSION_WRITER_TTL_MS) {- await sg.raw('update-ref', '-d', ref);- result.deletedStaleSessionRefs++;- }- } catch {}+ if (c.classification === 'agent' || c.classification === 'principal') {+ if (c.isPark) continue; // branch-switch state — never fold+ if (c.committedAtMs > 0 && now - c.committedAtMs >= SESSION_WRITER_TTL_MS) {+ aged.push({+ id: c.writerId,+ name: c.writerId,+ email: `${c.writerId}@openknowledge.local`,+ });+ }+ }+ }+ if (aged.length > 0) {+ try {+ await saveVersion(shadow, contentRoot, aged, branch, undefined, {+ checkpointKind: { foldedRefs: aged.length, trigger: 'ttl' },+ includeUpstream: false,+ timeoutMs: MAINTENANCE_GIT_TIMEOUT_MS,+ });+ result.deletedStaleSessionRefs += aged.length;+ } catch (err) {+ log.warn({ err, branch }, '[shadow-gc] TTL consolidation failed');}}}diff --git a/packages/server/src/shadow-maintenance-telemetry.ts b/packages/server/src/shadow-maintenance-telemetry.tsnew file mode 100644index 000000000..6fc7226ac--- /dev/null+++ b/packages/server/src/shadow-maintenance-telemetry.ts@@ -0,0 +1,59 @@+import type { Counter, Histogram } from '@opentelemetry/api';+import { getMeter } from './telemetry.ts';++export type MaintenanceOp = 'gc' | 'consolidation' | 'reap';++export type MaintenanceOutcome = 'ok' | 'skipped' | 'error';++export type ConsolidationTriggerLabel = 'dead-chain' | 'session-close' | 'boot' | 'ttl';++let _runDuration: Histogram | null = null;+let _gcLatch: Counter | null = null;+let _consolidation: Counter | null = null;++function runDurationHist(): Histogram {+ _runDuration ||= getMeter().createHistogram('ok.shadow.maintenance.run_duration_ms', {+ description:+ 'Wall-clock duration of one maintenance op. Bounded labels: op ∈ {gc, consolidation, reap}, outcome ∈ {ok, skipped, error}.',+ unit: 'ms',+ });+ return _runDuration;+}++function gcLatchCounter(): Counter {+ _gcLatch ||= getMeter().createCounter('ok.shadow.maintenance.gc_latch_total', {+ description:+ 'Distinct gc.log latch EPISODES (counted on the absent→present transition, not per observation, so one persistent ~1-day latch counts once). A latch means auto-gc is silently disabled until it self-expires; a nonzero rate means a repo is re-degrading invisibly.',+ });+ return _gcLatch;+}++function consolidationCounter(): Counter {+ _consolidation ||= getMeter().createCounter('ok.shadow.maintenance.consolidation_total', {+ description:+ 'Auto-consolidation runs that folded ≥1 dead chain. Bounded label: trigger ∈ {dead-chain, session-close, boot, ttl}. Width before/after ride the structured log, not metric labels.',+ });+ return _consolidation;+}++export function recordMaintenanceRun(+ op: MaintenanceOp,+ outcome: MaintenanceOutcome,+ durationMs: number,+): void {+ runDurationHist().record(Math.max(0, durationMs), { op, outcome });+}++export function recordGcLatch(): void {+ gcLatchCounter().add(1);+}++export function recordConsolidation(trigger: ConsolidationTriggerLabel): void {+ consolidationCounter().add(1, { trigger });+}++export function __resetMaintenanceTelemetryForTesting(): void {+ _runDuration = null;+ _gcLatch = null;+ _consolidation = null;+}diff --git a/packages/server/src/shadow-repo-stats.test.ts b/packages/server/src/shadow-repo-stats.test.tsnew file mode 100644index 000000000..07662fcd3--- /dev/null+++ b/packages/server/src/shadow-repo-stats.test.ts@@ -0,0 +1,98 @@+import { beforeEach, describe, expect, test } from 'bun:test';+import { mkdirSync, writeFileSync } from 'node:fs';+import { mkdtemp } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import simpleGit from 'simple-git';+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';+import { countStaleAgentWipRefs } from './shadow-repo-stats.ts';++let tmpDir: string;+let shadow: ShadowHandle;++beforeEach(async () => {+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-stale-stats-'));+ const projectRoot = resolve(tmpDir, 'project');+ const contentDir = resolve(projectRoot, 'content/docs');+ mkdirSync(contentDir, { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');+ await git.add('.');+ await git.commit('Initial commit');+ shadow = await initShadowRepo(projectRoot);+});++async function createRefAt(refname: string, isoDate: string, subject: string): Promise<void> {+ const sg = shadowGit(shadow);+ const emptyTreeSha = (await sg.raw('hash-object', '-t', 'tree', '-w', '/dev/null')).trim();+ const commitSha = (+ await sg+ .env({+ GIT_DIR: shadow.gitDir,+ GIT_AUTHOR_DATE: isoDate,+ GIT_COMMITTER_DATE: isoDate,+ GIT_AUTHOR_NAME: 'test',+ GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_COMMITTER_NAME: 'test',+ GIT_COMMITTER_EMAIL: '[email protected]',+ })+ .raw('commit-tree', emptyTreeSha, '-m', subject)+ ).trim();+ await sg.raw('update-ref', refname, commitSha);+}++const OLD = '2020-01-01T00:00:00+00:00'; // far past the staleness window+const NOW_ISH = new Date().toISOString();+const cutoff = () => Date.now() - 30 * 60 * 1000;++describe('countStaleAgentWipRefs (diagnose dead-agent-chain proxy)', () => {+ test('counts stale agent chains', async () => {+ await createRefAt('refs/wip/main/agent-a', OLD, 'wip: a');+ await createRefAt('refs/wip/main/agent-b', OLD, 'wip: b');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(2);+ });++ test('stale principal chains are NOT counted (folded by the 30-day TTL, not the fast path)', async () => {+ await createRefAt('refs/wip/main/agent-a', OLD, 'wip: a');+ await createRefAt('refs/wip/main/principal-b', OLD, 'wip: b');+ await createRefAt('refs/wip/main/principal-c', OLD, 'wip: c');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(1);+ });++ test('a fresh (recently-advanced) agent chain is NOT counted', async () => {+ await createRefAt('refs/wip/main/agent-live', NOW_ISH, 'wip: live');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(0);+ });++ test('non-session writers (file-system, git-upstream, service) are excluded', async () => {+ await createRefAt('refs/wip/main/file-system', OLD, 'wip: fs');+ await createRefAt('refs/wip/main/git-upstream', OLD, 'wip: upstream');+ await createRefAt('refs/wip/main/openknowledge-service', OLD, 'wip: svc');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(0);+ });++ test('park-tipped agent refs are excluded (branch-switch state, never folded)', async () => {+ await createRefAt('refs/wip/main/agent-parked', OLD, 'park: main -> feature');+ await createRefAt('refs/wip/main/agent-dead', OLD, 'wip: dead');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(1);+ });++ test('scans across branches (branch-agnostic, mirroring countWipRefs)', async () => {+ await createRefAt('refs/wip/main/agent-x', OLD, 'wip: x');+ await createRefAt('refs/wip/feature/agent-y', OLD, 'wip: y');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(2);+ });++ test('the staleness cutoff is the boundary: a ref committed after the cutoff is not counted', async () => {+ const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();+ await createRefAt('refs/wip/main/agent-recent', fiveMinAgo, 'wip: recent');+ expect(await countStaleAgentWipRefs(shadow, cutoff())).toBe(0);+ });++ test('no WIP refs → zero', async () => {+ expect(await countStaleAgentWipRefs(shadow, Date.now())).toBe(0);+ });+});diff --git a/packages/server/src/shadow-repo-stats.ts b/packages/server/src/shadow-repo-stats.tsnew file mode 100644index 000000000..4c36203b8--- /dev/null+++ b/packages/server/src/shadow-repo-stats.ts@@ -0,0 +1,80 @@+import { existsSync } from 'node:fs';+import { resolve } from 'node:path';+import { parseWriterId } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import type { ShadowHandle } from './shadow-repo.ts';+import { shadowGit } from './shadow-repo.ts';++export interface ShadowObjectStats {+ looseObjects: number;+ looseKiB: number;+ packfiles: number;+ packedObjects: number;+}++export async function countShadowObjects(shadow: ShadowHandle): Promise<ShadowObjectStats> {+ const sg = shadowGit(shadow);+ const raw = await sg.raw('count-objects', '-v');+ const fields = new Map<string, number>();+ for (const line of raw.split('\n')) {+ const idx = line.indexOf(':');+ if (idx < 0) continue;+ const key = line.slice(0, idx).trim();+ const value = Number.parseInt(line.slice(idx + 1).trim(), 10);+ if (key) fields.set(key, Number.isFinite(value) ? value : 0);+ }+ return {+ looseObjects: fields.get('count') ?? 0,+ looseKiB: fields.get('size') ?? 0,+ packfiles: fields.get('packs') ?? 0,+ packedObjects: fields.get('in-pack') ?? 0,+ };+}++export function hasGcLogLatch(shadow: ShadowHandle): boolean {+ return existsSync(resolve(shadow.gitDir, 'gc.log'));+}++export async function countWipRefs(shadow: ShadowHandle, branch?: string): Promise<number> {+ const sg = shadowGit(shadow);+ const pattern = branch ? `refs/wip/${branch}/` : 'refs/wip/';+ try {+ const raw = await sg.raw('for-each-ref', '--format=%(refname)', pattern);+ return raw.trim().split('\n').filter(Boolean).length;+ } catch {+ return 0;+ }+}++export async function countStaleAgentWipRefs(+ shadow: ShadowHandle,+ cutoffMs: number,+): Promise<number> {+ const sg = shadowGit(shadow);+ let lines: string[];+ try {+ lines = (+ await sg.raw(+ 'for-each-ref',+ '--format=%(refname)%00%(committerdate:unix)%00%(contents:subject)',+ 'refs/wip/',+ )+ )+ .trim()+ .split('\n')+ .filter(Boolean);+ } catch {+ return 0;+ }+ let count = 0;+ for (const line of lines) {+ const [refname = '', committerUnix = '', subject = ''] = line.split('\x00');+ if (subject.startsWith('park:')) continue; // branch-switch state — never folded+ const writerId = refname.split('/').slice(3).join('/');+ if (!writerId) continue;+ if (parseWriterId(writerId).classification !== 'agent') continue;+ const unix = Number.parseInt(committerUnix, 10);+ if (!Number.isFinite(unix)) continue; // unparseable date — do not treat as stale+ if (unix * 1000 < cutoffMs) count += 1;+ }+ return count;+}diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.tsindex 8f964035e..87aa7b0ef 100644--- a/packages/server/src/shadow-repo.test.ts+++ b/packages/server/src/shadow-repo.test.ts@@ -4,17 +4,24 @@ import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';-import { parseCheckpoint, parseOkActor } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import {+ formatCheckpointBodyLine,+ parseCheckpoint,+ parseOkActor,+} from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';import {buildWipTree,commitUpstreamImport,commitWip,+ DEFAULT_CHECKPOINT_RETENTION,+ GIT_UPSTREAM_WRITER,type InMemoryCheckpointParams,initShadowRepo,type ParkableDoc,parkBranch,readParkedState,+ resetFoldedWipRefs,SERVICE_WRITER,type ShadowHandle,safetyCheckpoint,@@ -642,6 +649,145 @@ describe('saveVersion', () => {const parents = parentLine.split(' ').filter(Boolean);expect(parents).toContain(checkpoint1Sha);});++ test('D21: every checkpoint adopts the latest prior checkpoint as a parent (even with WIP activity)', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# v1\n');+ await commitWip(shadow, human, 'content/docs', 'WIP: v1');+ const result1 = await saveVersion(shadow, 'content/docs', [human]);+ const sg = shadowGit(shadow);+ const checkpoint1Sha = (await sg.raw('rev-parse', result1.checkpointRef)).trim();++ writeFileSync(resolve(contentDir, 'intro.md'), '# v2\n');+ const wip2 = await commitWip(shadow, human, 'content/docs', 'WIP: v2');+ const result2 = await saveVersion(shadow, 'content/docs', [human]);++ const parents = (await sg.raw('log', '-1', '--format=%P', result2.checkpointRef))+ .trim()+ .split(' ')+ .filter(Boolean);+ expect(parents).toContain(wip2); // WIP tip is still a parent+ expect(parents).toContain(checkpoint1Sha); // AND the prior checkpoint is chained+ const reachable = (await sg.raw('rev-list', result2.checkpointRef)).trim().split('\n');+ expect(reachable).toContain(checkpoint1Sha);+ });++ test('M3: checkpoints a feature branch (branch threaded through the spine)', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# feature work\n');+ await commitWip(shadow, human, 'content/docs', 'WIP: feature', 'feature-x');+ const sg = shadowGit(shadow);+ expect((await sg.raw('rev-parse', 'refs/wip/feature-x/human-ada')).trim()).toHaveLength(40);++ const result = await saveVersion(shadow, 'content/docs', [human], 'feature-x');+ expect(result.checkpointRef).toContain('refs/checkpoints/feature-x/');++ let featureWipGone = false;+ try {+ await sg.raw('rev-parse', 'refs/wip/feature-x/human-ada');+ } catch {+ featureWipGone = true;+ }+ expect(featureWipGone).toBe(true);+ });++ test('M6: concurrent saveVersion calls use isolated scratch indexes (no corruption)', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# human\n');+ await commitWip(shadow, human, 'content/docs', 'WIP: human');+ writeFileSync(resolve(contentDir, 'intro.md'), '# agent\n');+ await commitWip(shadow, agent, 'content/docs', 'WIP: agent');++ const [r1, r2] = await Promise.all([+ saveVersion(shadow, 'content/docs', [human]),+ saveVersion(shadow, 'content/docs', [agent]),+ ]);++ const sg = shadowGit(shadow);+ for (const r of [r1, r2]) {+ const sha = (await sg.raw('rev-parse', r.checkpointRef)).trim();+ expect(sha).toHaveLength(40);+ const tree = (await sg.raw('ls-tree', '-r', '--name-only', r.checkpointRef)).trim();+ expect(tree).toContain('content/docs/intro.md');+ }+ });++ test('resetFoldedWipRefs skips a ref advanced past the snapshot, deletes a matching one', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# agent v1\n');+ const agentV1 = await commitWip(shadow, agent, 'content/docs', 'WIP: agent v1');+ writeFileSync(resolve(contentDir, 'intro.md'), '# human stable\n');+ const humanSha = await commitWip(shadow, human, 'content/docs', 'WIP: human stable');++ const snapshot = new Map([+ [agent.id, agentV1],+ [human.id, humanSha],+ ]);++ writeFileSync(resolve(contentDir, 'intro.md'), '# agent v2\n');+ const agentV2 = await commitWip(shadow, agent, 'content/docs', 'WIP: agent v2');++ const sg = shadowGit(shadow);+ await resetFoldedWipRefs(sg, 'main', [agent, human], snapshot);++ expect((await sg.raw('rev-parse', `refs/wip/main/${agent.id}`)).trim()).toBe(agentV2);+ let humanGone = false;+ try {+ await sg.raw('rev-parse', `refs/wip/main/${human.id}`);+ } catch {+ humanGone = true;+ }+ expect(humanGone).toBe(true);+ });++ test('includeUpstream:false does not fold or reset the git-upstream chain', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# agent\n');+ const agentSha = await commitWip(shadow, agent, 'content/docs', 'WIP: agent');+ writeFileSync(resolve(contentDir, 'intro.md'), '# upstream import\n');+ const upstreamSha = await commitWip(+ shadow,+ GIT_UPSTREAM_WRITER,+ 'content/docs',+ 'WIP: upstream',+ );++ const result = await saveVersion(shadow, 'content/docs', [agent], 'main', undefined, {+ includeUpstream: false,+ });++ const sg = shadowGit(shadow);+ const parents = (await sg.raw('log', '-1', '--format=%P', result.checkpointRef))+ .trim()+ .split(' ')+ .filter(Boolean);+ expect(parents).toContain(agentSha);+ expect(parents).not.toContain(upstreamSha);+ expect((await sg.raw('rev-parse', `refs/wip/main/${GIT_UPSTREAM_WRITER.id}`)).trim()).toBe(+ upstreamSha,+ );+ });++ test('D9: checkpointKind tags the checkpoint as auto-consolidation', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# consolidated\n');+ await commitWip(shadow, agent, 'content/docs', 'WIP: agent');+ const result = await saveVersion(shadow, 'content/docs', [agent], 'main', undefined, {+ checkpointKind: { foldedRefs: 4, trigger: 'dead-chain' },+ });++ const sg = shadowGit(shadow);+ const body = (await sg.raw('log', '-1', '--format=%B', result.checkpointRef)).trim();+ const parsed = parseCheckpoint(body);+ expect(parsed?.kind).toBe('auto-consolidation');+ if (parsed?.kind === 'auto-consolidation') {+ expect(parsed.metadata.foldedRefs).toBe(4);+ expect(parsed.metadata.trigger).toBe('dead-chain');+ }+ });++ test('user Save Version checkpoints stay untyped (no auto-consolidation tag)', async () => {+ writeFileSync(resolve(contentDir, 'intro.md'), '# user save\n');+ await commitWip(shadow, human, 'content/docs', 'WIP: human');+ const result = await saveVersion(shadow, 'content/docs', [human]);+ const sg = shadowGit(shadow);+ const body = (await sg.raw('log', '-1', '--format=%B', result.checkpointRef)).trim();+ expect(parseCheckpoint(body)).toBe(null); // untyped = permanent (D17/D21)+ });});describe('saveInMemoryCheckpoint (bridge-correctness SPEC §6 R7a)', () => {@@ -805,6 +951,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)const result = await gcCheckpointRefs(shadow, 'main', {maxBridgeMergeLoss: 3,maxExternalChangeRescue: 50,+ maxAutoConsolidation: 2,ttlMs: 0, // disable TTL; only count-based cap applies});@@ -838,6 +985,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)const result = await gcCheckpointRefs(shadow, 'main', {maxBridgeMergeLoss: 50,maxExternalChangeRescue: 50,+ maxAutoConsolidation: 2,ttlMs: 1, // everything older than 1 ms is eligible});@@ -873,6 +1021,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)const result = await gcCheckpointRefs(shadow, 'main', {maxBridgeMergeLoss: 0, // forces deletion of the typed checkpointmaxExternalChangeRescue: 0,+ maxAutoConsolidation: 2,ttlMs: 0,});@@ -884,6 +1033,91 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5).filter(Boolean);expect(refs).toContain(`refs/checkpoints/main/${untypedSha}`);});++ async function writeAutoConsolidationCheckpoint(+ s: ShadowHandle,+ foldedRefs: number,+ ageRank = foldedRefs,+ ): Promise<string> {+ const sg = shadowGit(s);+ const emptyTreeSha = (await sg.raw('hash-object', '-t', 'tree', '-w', '/dev/null')).trim();+ const body = `checkpoint: consolidated ${foldedRefs} inactive sessions\n\n${formatCheckpointBodyLine(+ {+ kind: 'auto-consolidation',+ docName: null,+ size: null,+ metadata: { foldedRefs, trigger: 'dead-chain' },+ },+ )}`;+ const date = `@${1_700_000_000 + ageRank * 100} +0000`;+ const sha = (+ await sg+ .env({+ GIT_DIR: s.gitDir,+ GIT_AUTHOR_NAME: 'openknowledge-service',+ GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_AUTHOR_DATE: date,+ GIT_COMMITTER_NAME: 'openknowledge-service',+ GIT_COMMITTER_EMAIL: '[email protected]',+ GIT_COMMITTER_DATE: date,+ })+ .raw('commit-tree', emptyTreeSha, '-m', body)+ ).trim();+ await sg.raw('update-ref', `refs/checkpoints/main/${sha}`, sha);+ return sha;+ }++ test('A3: adding the auto-consolidation kind does not throw the byKind partition', async () => {+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ await writeAutoConsolidationCheckpoint(shadow, 3);+ const result = await gcCheckpointRefs(shadow, 'main', DEFAULT_CHECKPOINT_RETENTION);+ expect(result.scanned).toBe(1);+ expect(result.deletedAutoConsolidation).toBe(0); // under the keep-newest-2 cap+ });++ test('keeps only the newest 2 auto-consolidation refs (count-only, D21)', async () => {+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ const shas: string[] = [];+ for (let i = 0; i < 5; i++) {+ shas.push(await writeAutoConsolidationCheckpoint(shadow, i + 1, i + 1));+ }++ const result = await gcCheckpointRefs(shadow, 'main', {+ maxBridgeMergeLoss: 50,+ maxExternalChangeRescue: 50,+ maxAutoConsolidation: 2,+ ttlMs: 0,+ });++ expect(result.scanned).toBe(5);+ expect(result.deletedAutoConsolidation).toBe(3); // 5 - 2 kept++ const sg = shadowGit(shadow);+ const remaining = (+ await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/main/')+ )+ .trim()+ .split('\n')+ .filter(Boolean);+ expect(remaining).toHaveLength(2);+ expect(remaining).toContain(`refs/checkpoints/main/${shas[4]}`);+ expect(remaining).toContain(`refs/checkpoints/main/${shas[3]}`);+ });++ test('TTL never reaps auto-consolidation refs (chained history must stay anchored)', async () => {+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ await writeAutoConsolidationCheckpoint(shadow, 1);+ await writeAutoConsolidationCheckpoint(shadow, 2);++ const result = await gcCheckpointRefs(shadow, 'main', {+ maxBridgeMergeLoss: 50,+ maxExternalChangeRescue: 50,+ maxAutoConsolidation: 2,+ ttlMs: 1,+ });++ expect(result.deletedAutoConsolidation).toBe(0);+ });});describe('sweepLegacyShadowRefs (US-018, D35, NFR-6)', () => {diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.tsindex 16eea7a08..6fbf80d7d 100644--- a/packages/server/src/shadow-repo.ts+++ b/packages/server/src/shadow-repo.ts@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';import { existsSync, readdirSync, rmSync } from 'node:fs';import { resolve } from 'node:path';import {+ type AutoConsolidationTrigger,formatCheckpointBodyLine,formatCheckpointSubject,formatImportSubject,@@ -12,6 +13,7 @@ import {parseCheckpoint,parseWriterId,resolveShadowDir,+ type WriterClassification,} from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';import { tracedMkdirSync, tracedRenameSync, tracedWriteFileSync } from './fs-traced.ts';@@ -41,16 +43,81 @@ const GIT_TIMEOUT_MS = (() => {return Number.isFinite(parsed) && parsed > 0 ? parsed : 30_000;})();-export function shadowGit(shadow: ShadowHandle) {+export const MAINTENANCE_GIT_TIMEOUT_MS = (() => {+ const raw = process.env.OK_SHADOW_MAINTENANCE_GC_TIMEOUT_MS;+ if (!raw) return 600_000;+ const parsed = Number.parseInt(raw, 10);+ return Number.isFinite(parsed) && parsed > 0 ? parsed : 600_000;+})();++const SHADOW_GC_AUTO = 512;++export function shadowGit(shadow: ShadowHandle, opts?: { timeoutMs?: number }) {return simpleGit({baseDir: shadow.workTree,- timeout: { block: GIT_TIMEOUT_MS },+ timeout: { block: opts?.timeoutMs ?? GIT_TIMEOUT_MS },}).env({GIT_DIR: shadow.gitDir,GIT_WORK_TREE: shadow.workTree,});}+export async function configureShadowGc(shadow: ShadowHandle): Promise<void> {+ const sg = shadowGit(shadow);+ await sg.raw('config', 'gc.auto', String(SHADOW_GC_AUTO));+ await sg.raw('config', 'gc.autoDetach', 'false');+ await sg.raw('config', 'gc.writeCommitGraph', 'true');+ await sg.raw('config', 'commitGraph.changedPaths', 'true');+}++/** One WIP chain on a branch — its writer id, tip, classification, whether the+ * tip is a park commit (branch-switch state that must never be folded), and the+ * tip's committer time (for the TTL backstop's age check). */+export interface WipChainInfo {+ writerId: string;+ tipSha: string;+ classification: WriterClassification;+ isPark: boolean;+ committedAtMs: number;+}++export async function enumerateWipChains(+ shadow: ShadowHandle,+ branch: string,+): Promise<WipChainInfo[]> {+ const sg = shadowGit(shadow);+ let lines: string[];+ try {+ lines = (+ await sg.raw(+ 'for-each-ref',+ '--format=%(refname)%00%(objectname)%00%(committerdate:unix)%00%(contents:subject)',+ `refs/wip/${branch}/`,+ )+ )+ .trim()+ .split('\n')+ .filter(Boolean);+ } catch {+ return [];+ }+ const out: WipChainInfo[] = [];+ for (const line of lines) {+ const [refname = '', tipSha = '', committerUnix = '', subject = ''] = line.split('\x00');+ const writerId = refname.split('/').slice(3).join('/');+ if (!writerId) continue;+ const unix = Number.parseInt(committerUnix, 10);+ out.push({+ writerId,+ tipSha,+ classification: parseWriterId(writerId).classification,+ isPark: subject.startsWith('park:'),+ committedAtMs: Number.isFinite(unix) ? unix * 1000 : 0,+ });+ }+ return out;+}+export async function initShadowRepo(projectRoot: string): Promise<ShadowHandle> {const shadowDir = resolveShadowDir(projectRoot);@@ -78,6 +145,13 @@ export async function initShadowRepo(projectRoot: string): Promise<ShadowHandle>}const handle: ShadowHandle = { gitDir: shadowDir, workTree: projectRoot };++ try {+ await configureShadowGc(handle);+ } catch (e) {+ console.warn('[shadow-repo] failed to write gc config (non-fatal):', e);+ }+await sweepLegacyShadowRefs(handle);sweepOrphanedTmpIndexFiles(handle);@@ -598,12 +672,14 @@ export async function listRescueCheckpoints(export interface CheckpointRetentionPolicy {maxBridgeMergeLoss: number;maxExternalChangeRescue: number;+ maxAutoConsolidation: number;ttlMs: number;}export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {maxBridgeMergeLoss: 50,maxExternalChangeRescue: 50,+ maxAutoConsolidation: 2,ttlMs: 30 * 24 * 60 * 60 * 1000,};@@ -611,6 +687,7 @@ export interface CheckpointGcResult {scanned: number;deletedBridgeMergeLoss: number;deletedExternalChangeRescue: number;+ deletedAutoConsolidation: number;retained: number;}@@ -623,6 +700,7 @@ export async function gcCheckpointRefs(scanned: 0,deletedBridgeMergeLoss: 0,deletedExternalChangeRescue: 0,+ deletedAutoConsolidation: 0,retained: 0,};const sg = shadowGit(shadow);@@ -670,10 +748,11 @@ export async function gcCheckpointRefs(return result;}+ type TypedKind = 'bridge-merge-loss' | 'external-change-rescue' | 'auto-consolidation';interface Entry {sha: string;timestamp: number; // ms since epoch- kind: 'bridge-merge-loss' | 'external-change-rescue' | null;+ kind: TypedKind | null;}const entries: Entry[] = [];for (const record of logRaw.split('\x1e')) {@@ -687,9 +766,10 @@ export async function gcCheckpointRefs(entries.push({ sha, timestamp: Number.isFinite(ts) ? ts : 0, kind });}- const byKind: Record<'bridge-merge-loss' | 'external-change-rescue', Entry[]> = {+ const byKind: Record<TypedKind, Entry[]> = {'bridge-merge-loss': [],'external-change-rescue': [],+ 'auto-consolidation': [],};let retainedUntyped = 0;for (const e of entries) {@@ -705,7 +785,8 @@ export async function gcCheckpointRefs(const planDeletions = (list: Entry[],limit: number,- counter: 'deletedBridgeMergeLoss' | 'deletedExternalChangeRescue',+ counter: 'deletedBridgeMergeLoss' | 'deletedExternalChangeRescue' | 'deletedAutoConsolidation',+ applyTtl = true,): void => {list.sort((a, b) => b.timestamp - a.timestamp);for (let i = 0; i < list.length; i++) {@@ -713,7 +794,7 @@ export async function gcCheckpointRefs(if (!entry) continue;const overCount = i >= limit;const overTtl =- policy.ttlMs > 0 && entry.timestamp > 0 && now - entry.timestamp > policy.ttlMs;+ applyTtl && policy.ttlMs > 0 && entry.timestamp > 0 && now - entry.timestamp > policy.ttlMs;if (overCount || overTtl) {const ref = shaToRef.get(entry.sha);if (ref) {@@ -729,6 +810,12 @@ export async function gcCheckpointRefs(policy.maxExternalChangeRescue,'deletedExternalChangeRescue',);+ planDeletions(+ byKind['auto-consolidation'],+ policy.maxAutoConsolidation,+ 'deletedAutoConsolidation',+ false,+ );for (const ref of deleteRefs) {try {@@ -887,12 +974,19 @@ export interface SaveVersionResult {checkpointRef: string;}+export interface SaveVersionOptions {+ checkpointKind?: { foldedRefs: number; trigger: AutoConsolidationTrigger };+ includeUpstream?: boolean;+ timeoutMs?: number;+}+export async function saveVersion(shadow: ShadowHandle,contentRoot: string,writers: WriterIdentity[],branch = 'main',summary?: string,+ options?: SaveVersionOptions,): Promise<SaveVersionResult> {return withSpan('shadow.saveVersion',@@ -900,9 +994,10 @@ export async function saveVersion(attributes: {'shadow.branch': branch,'shadow.writer_count': writers.length,+ 'shadow.checkpoint_kind': options?.checkpointKind ? 'auto-consolidation' : 'user',},},- async () => saveVersionInner(shadow, contentRoot, writers, branch, summary),+ async () => saveVersionInner(shadow, contentRoot, writers, branch, summary, options),);}@@ -912,11 +1007,12 @@ async function saveVersionInner(writers: WriterIdentity[],branch = 'main',summary?: string,+ options?: SaveVersionOptions,): Promise<SaveVersionResult> {- const sg = shadowGit(shadow);+ const sg = shadowGit(shadow, options?.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined);const gitPathspec = contentRoot || '.';- const shadowTmpIndex = resolve(shadow.gitDir, 'index-checkpoint');+ const shadowTmpIndex = resolve(shadow.gitDir, `index-checkpoint-${randomUUID()}`);try {await sg.env({@@ -929,31 +1025,33 @@ async function saveVersionInner(await sg.env({ GIT_DIR: shadow.gitDir, GIT_INDEX_FILE: shadowTmpIndex }).raw('write-tree')).trim();+ const foldWriters =+ options?.includeUpstream === false ? writers : [...writers, GIT_UPSTREAM_WRITER];const shadowParentShas: string[] = [];- for (const w of [...writers, GIT_UPSTREAM_WRITER]) {+ const wipSnapshotShas = new Map<string, string>(); // writerId -> sha at snapshot+ for (const w of foldWriters) {try {const sha = (await sg.raw('rev-parse', `refs/wip/${branch}/${w.id}`)).trim();shadowParentShas.push(sha);+ wipSnapshotShas.set(w.id, sha);} catch {}}const uniqueParents = [...new Set(shadowParentShas)];- if (uniqueParents.length === 0) {- try {- const refs = (- await sg.raw(- 'for-each-ref',- '--sort=-creatordate',- '--format=%(objectname)',- `refs/checkpoints/${branch}/`,- )+ try {+ const priorCheckpoint = (+ await sg.raw(+ 'for-each-ref',+ '--sort=-creatordate',+ '--count=1',+ '--format=%(objectname)',+ `refs/checkpoints/${branch}/`,)- .trim()- .split('\n')- .filter(Boolean);- if (refs[0]) uniqueParents.push(refs[0]);- } catch {}- }+ ).trim();+ if (priorCheckpoint && !uniqueParents.includes(priorCheckpoint)) {+ uniqueParents.push(priorCheckpoint);+ }+ } catch {}const checkpointActorEntry: OkActorEntry = {v: 1,@@ -969,7 +1067,18 @@ async function saveVersionInner(docs: [],};const checkpointSubject = summary?.trim() ? summary.trim() : 'Checkpoint version';- const checkpointMessage = `${formatCheckpointSubject(checkpointSubject)}\n\n${formatOkActor(checkpointActorEntry)}`;+ let checkpointMessage = `${formatCheckpointSubject(checkpointSubject)}\n\n${formatOkActor(checkpointActorEntry)}`;+ if (options?.checkpointKind) {+ checkpointMessage += `\n${formatCheckpointBodyLine({+ kind: 'auto-consolidation',+ docName: null,+ size: null,+ metadata: {+ foldedRefs: options.checkpointKind.foldedRefs,+ trigger: options.checkpointKind.trigger,+ },+ })}`;+ }const checkpointArgs = ['commit-tree', shadowTreeSha, '-m', checkpointMessage];for (const p of uniqueParents) {checkpointArgs.push('-p', p);@@ -990,14 +1099,7 @@ async function saveVersionInner(const checkpointRef = `refs/checkpoints/${branch}/${checkpointSha}`;await sg.raw('update-ref', checkpointRef, checkpointSha);- for (const w of writers) {- try {- await sg.raw('update-ref', '-d', `refs/wip/${branch}/${w.id}`);- } catch {}- }- try {- await sg.raw('update-ref', '-d', `refs/wip/${branch}/${GIT_UPSTREAM_WRITER.id}`);- } catch {}+ await resetFoldedWipRefs(sg, branch, foldWriters, wipSnapshotShas);return { checkpointRef };} finally {@@ -1006,3 +1108,19 @@ async function saveVersionInner(} catch {}}}++export async function resetFoldedWipRefs(+ sg: ReturnType<typeof shadowGit>,+ branch: string,+ writers: readonly { id: string }[],+ wipSnapshotShas: ReadonlyMap<string, string>,+): Promise<void> {+ for (const w of writers) {+ const ref = `refs/wip/${branch}/${w.id}`;+ const expected = wipSnapshotShas.get(w.id);+ if (expected === undefined) continue; // had no WIP ref at snapshot — nothing to reset+ try {+ await sg.raw('update-ref', '-d', ref, expected);+ } catch {}+ }+}diff --git a/packages/server/src/single-flight.test.ts b/packages/server/src/single-flight.test.tsnew file mode 100644index 000000000..61945ec23--- /dev/null+++ b/packages/server/src/single-flight.test.ts@@ -0,0 +1,68 @@+import { describe, expect, test } from 'bun:test';+import { createSingleFlight } from './single-flight.ts';++describe('createSingleFlight (PRD-6972 FR2)', () => {+ test('N concurrent identical keys run fn exactly once and share one result', async () => {+ const sf = createSingleFlight<number>();+ let calls = 0;+ let resolveWalk: (v: number) => void = () => {};+ const gate = new Promise<number>((r) => {+ resolveWalk = r;+ });+ const fn = () => {+ calls += 1;+ return gate;+ };++ const runs = Array.from({ length: 5 }, () => sf.run('k', fn));+ expect(calls).toBe(1); // exactly one git walk+ expect(runs.filter((r) => r.coalesced)).toHaveLength(4); // N-1 coalesced+ expect(sf.size).toBe(1);++ resolveWalk(42);+ const results = await Promise.all(runs.map((r) => r.promise));+ expect(results).toEqual([42, 42, 42, 42, 42]); // N identical responses+ });++ test('distinct keys run independently', async () => {+ const sf = createSingleFlight<string>();+ let calls = 0;+ const fn = (v: string) => () => {+ calls += 1;+ return Promise.resolve(v);+ };+ const a = sf.run('a', fn('a'));+ const b = sf.run('b', fn('b'));+ expect(calls).toBe(2);+ expect(a.coalesced).toBe(false);+ expect(b.coalesced).toBe(false);+ expect(await a.promise).toBe('a');+ expect(await b.promise).toBe('b');+ });++ test('entry evicts on settle (success) so a later identical key re-runs', async () => {+ const sf = createSingleFlight<number>();+ let calls = 0;+ const fn = () => {+ calls += 1;+ return Promise.resolve(calls);+ };++ const first = sf.run('k', fn);+ await first.promise;+ await Promise.resolve();+ expect(sf.size).toBe(0);++ const second = sf.run('k', fn);+ expect(second.coalesced).toBe(false); // fresh run, not a stale shared result+ expect(await second.promise).toBe(2);+ });++ test('entry evicts on settle (error) and does not leak', async () => {+ const sf = createSingleFlight<number>();+ const failing = sf.run('k', () => Promise.reject(new Error('walk failed')));+ await expect(failing.promise).rejects.toThrow('walk failed');+ await Promise.resolve();+ expect(sf.size).toBe(0);+ });+});diff --git a/packages/server/src/single-flight.ts b/packages/server/src/single-flight.tsnew file mode 100644index 000000000..cb4800822--- /dev/null+++ b/packages/server/src/single-flight.ts@@ -0,0 +1,29 @@+interface SingleFlightRun<T> {+ promise: Promise<T>;+ coalesced: boolean;+}++export interface SingleFlight<T> {+ run(key: string, fn: () => Promise<T>): SingleFlightRun<T>;+ readonly size: number;+}++export function createSingleFlight<T>(): SingleFlight<T> {+ const inflight = new Map<string, Promise<T>>();+ return {+ run(key, fn) {+ const existing = inflight.get(key);+ if (existing) return { promise: existing, coalesced: true };+ const promise = fn();+ inflight.set(key, promise);+ const evict = (): void => {+ if (inflight.get(key) === promise) inflight.delete(key);+ };+ promise.then(evict, evict);+ return { promise, coalesced: false };+ },+ get size() {+ return inflight.size;+ },+ };+}diff --git a/packages/server/src/timeline-query.test.ts b/packages/server/src/timeline-query.test.tsindex afbfc1c44..29780ad41 100644--- a/packages/server/src/timeline-query.test.ts+++ b/packages/server/src/timeline-query.test.ts@@ -1,4 +1,5 @@import { afterEach, beforeEach, describe, expect, test } from 'bun:test';+import { execFileSync } from 'node:child_process';import { mkdirSync, rmSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';@@ -24,7 +25,7 @@ import {saveVersion,type WriterIdentity,} from './shadow-repo';-import { getDocumentHistory } from './timeline-query';+import { getDocumentHistory, historyWalkCap } from './timeline-query';let tmpDir: string;@@ -651,3 +652,107 @@ describe('getDocumentHistory — rename-history mitigation (US-004)', () => {expect(result.entries.every((e) => e.type === 'checkpoint')).toBe(true);});});++describe('depth-bound history walk (PRD-6972 FR3 / D14)', () => {+ test('historyWalkCap: 3x(offset+limit) with a 500-commit ceiling', () => {+ expect(historyWalkCap(0, 50)).toBe(150); // 3 * 50+ expect(historyWalkCap(0, 2)).toBe(6);+ expect(historyWalkCap(100, 50)).toBe(450); // 3 * 150+ expect(historyWalkCap(200, 50)).toBe(500); // 3 * 250 = 750 → ceiling 500+ expect(historyWalkCap(10_000, 10)).toBe(500); // ceiling+ for (const [o, l] of [+ [0, 50],+ [50, 50],+ [149, 50],+ ] as const) {+ expect(historyWalkCap(o, l)).toBeGreaterThan(o);+ }+ });++ function buildDeepDocChain(shadow: Awaited<ReturnType<typeof setup>>['shadow'], n: number) {+ const ref = 'refs/wip/main/human-ada';+ let stream = `reset ${ref}\n`;+ for (let i = 0; i < n; i++) {+ const content = `# Edit ${i}\n`;+ const msg = `wip: edit ${i}`;+ const ts = 1_700_000_000 + i; // monotonically increasing author/commit date+ const blobMark = 2 * i + 1;+ const commitMark = 2 * i + 2;+ stream += `blob\nmark :${blobMark}\ndata ${Buffer.byteLength(content)}\n${content}\n`;+ stream += `commit ${ref}\nmark :${commitMark}\n`;+ stream += `author Ada <[email protected]> ${ts} +0000\n`;+ stream += `committer Ada <[email protected]> ${ts} +0000\n`;+ stream += `data ${Buffer.byteLength(msg)}\n${msg}\n`;+ stream += `M 100644 :${blobMark} content/docs/intro.md\n\n`;+ }+ stream += 'done\n';+ execFileSync('git', ['fast-import', '--done'], {+ cwd: shadow.workTree,+ env: { ...process.env, GIT_DIR: shadow.gitDir, GIT_WORK_TREE: shadow.workTree },+ input: stream,+ stdio: ['pipe', 'ignore', 'ignore'],+ });+ }++ test('bounds the walk on a >500-commit doc; saturates hasMore; paginates within window', async () => {+ const { shadow } = await setup();+ buildDeepDocChain(shadow, 505);++ const page0 = await getDocumentHistory(+ shadow,+ { docName: 'intro', limit: 50, offset: 0 },+ 'content/docs',+ );+ expect(page0.entries).toHaveLength(50);+ expect(page0.total).toBeLessThanOrEqual(150);+ expect(page0.hasMore).toBe(true);++ const page1 = await getDocumentHistory(+ shadow,+ { docName: 'intro', limit: 50, offset: 50 },+ 'content/docs',+ );+ expect(page1.entries).toHaveLength(50);+ expect(page1.hasMore).toBe(true);+ const page0Shas = new Set(page0.entries.map((e) => e.sha));+ expect(page1.entries.every((e) => !page0Shas.has(e.sha))).toBe(true);++ const beyond = await getDocumentHistory(+ shadow,+ { docName: 'intro', limit: 10, offset: 500 },+ 'content/docs',+ );+ expect(beyond.entries).toHaveLength(0);+ expect(beyond.hasMore).toBe(false);+ }, 180_000);++ test('does NOT falsely saturate when commits are under the cap', async () => {+ const { shadow, contentDir } = await setup();+ for (let i = 0; i < 5; i++) {+ writeFileSync(resolve(contentDir, 'intro.md'), `# Edit ${i}\n`);+ await commitWip(shadow, human, 'content/docs', `WIP: edit ${i}`);+ }+ const result = await getDocumentHistory(+ shadow,+ { docName: 'intro', limit: 50, offset: 0 },+ 'content/docs',+ );+ expect(result.entries.length).toBe(5);+ expect(result.hasMore).toBe(false);+ });++ test('noise-dominated multi-writer fixture still fills a full page (slack absorbs filtering)', async () => {+ const { shadow, contentDir } = await setup();+ for (let i = 0; i < 24; i++) {+ const w = i % 2 === 0 ? human : agent;+ writeFileSync(resolve(contentDir, 'intro.md'), `# Edit ${i}\n`);+ await commitWip(shadow, w, 'content/docs', `WIP: edit ${i}`);+ }+ const result = await getDocumentHistory(+ shadow,+ { docName: 'intro', limit: 10, offset: 0 },+ 'content/docs',+ );+ expect(result.entries).toHaveLength(10);+ }, 60_000);+});diff --git a/packages/server/src/timeline-query.ts b/packages/server/src/timeline-query.tsindex 6e3204f0f..2b9c54348 100644--- a/packages/server/src/timeline-query.ts+++ b/packages/server/src/timeline-query.ts@@ -22,6 +22,12 @@ import {import type { ShadowHandle } from './shadow-repo.ts';import { shadowGit } from './shadow-repo.ts';import { getMeter, withSpan } from './telemetry.ts';+import { recordTimelineQuery } from './timeline-telemetry.ts';++const HISTORY_WALK_CEILING = 500;+export function historyWalkCap(offset: number, limit: number): number {+ return Math.min(HISTORY_WALK_CEILING, 3 * (Math.max(0, offset) + Math.max(1, limit)));+}interface HistoryQuery {docName: string;@@ -29,6 +35,7 @@ interface HistoryQuery {type?: string | string[];author?: string | string[];excludeAuthor?: string | string[];+ includeAutoCheckpoints?: boolean;limit?: number;offset?: number;}@@ -217,9 +224,22 @@ export async function getDocumentHistory(const limit = Math.max(1, query.limit ?? 50);const offset = Math.max(0, query.offset ?? 0);+ const walkCap = historyWalkCap(offset, limit);+ const queryStart = performance.now();+ let windowSaturated = false;+ const finishMetric = (width: number, commits: number, error = false): void =>+ recordTimelineQuery({+ durationMs: performance.now() - queryStart,+ width,+ commits,+ capped: windowSaturated,+ error,+ });+const typeFilter = toArray(query.type);const authorFilter = toArray(query.author);const excludeAuthorFilter = toArray(query.excludeAuthor);+ const includeAuto = query.includeAutoCheckpoints ?? false;const normalizedRoot = contentRoot === '.' ? '' : contentRoot.replace(/^\.\//, '');const pathFor = (name: string): string =>@@ -316,6 +336,7 @@ export async function getDocumentHistory(const filtered = allEntries.filter((e) =>+ (includeAuto || e.checkpoint?.kind !== 'auto-consolidation') &&matchesAuthor(e, authorFilter) &&(excludeAuthorFilter.length === 0 || !matchesAuthor(e, excludeAuthorFilter)),);@@ -323,6 +344,7 @@ export async function getDocumentHistory(const total = filtered.length;const page = filtered.slice(offset, offset + limit);const stripped: TimelineEntry[] = page.map(({ rawBody: _rawBody, ...rest }) => rest);+ finishMetric(allShas.length, total);return { entries: stripped, total, hasMore: offset + limit < total };}@@ -430,10 +452,13 @@ export async function getDocumentHistory('--full-history','--author-date-order',`--format=${GIT_LOG_FORMAT}`,+ '-n',+ String(walkCap),...allStartRefs,...(docPath ? ['--', docPath] : []),);wipEntries = parseGitLogOutput(currentRaw);+ if (wipEntries.length >= walkCap) windowSaturated = true;if (hasRenameHistory) {for (let i = 0; i < chain.length - 1; i++) {@@ -445,11 +470,19 @@ export async function getDocumentHistory(const predecessorPath = pathFor(step.path);const predRaw = await logSeededReachable(shadow,- ['--full-history', '--author-date-order', `--format=${GIT_LOG_FORMAT}`],+ [+ '--full-history',+ '--author-date-order',+ `--format=${GIT_LOG_FORMAT}`,+ '-n',+ String(walkCap),+ ],seeds,predecessorPath,);- wipEntries = [...wipEntries, ...parseGitLogOutput(predRaw)];+ const predEntries = parseGitLogOutput(predRaw);+ if (predEntries.length >= walkCap) windowSaturated = true;+ wipEntries = [...wipEntries, ...predEntries];} catch (e) {console.warn(`[timeline] predecessor walk failed for step ${i} (${step.path}); skipping:`,@@ -490,6 +523,10 @@ export async function getDocumentHistory(filtered = filtered.filter((e) => e.type !== 'park');+ if (!includeAuto) {+ filtered = filtered.filter((e) => e.checkpoint?.kind !== 'auto-consolidation');+ }+if (typeFilter.length > 0) {filtered = filtered.filter((e) => typeFilter.includes(e.type));}@@ -505,9 +542,15 @@ export async function getDocumentHistory(const total = filtered.length;const page = filtered.slice(offset, offset + limit);const stripped: TimelineEntry[] = page.map(({ rawBody: _rawBody, ...rest }) => rest);- return { entries: stripped, total, hasMore: offset + limit < total };+ finishMetric(allStartRefs.length, unique.length);+ return {+ entries: stripped,+ total,+ hasMore: (windowSaturated && page.length > 0) || offset + limit < total,+ };} catch (e) {console.warn('[timeline] getDocumentHistory failed, returning empty result:', e);+ finishMetric(0, 0, true);return EMPTY;}}@@ -543,19 +586,24 @@ export async function getFolderTimeline(}if (startRefs.length === 0) return EMPTY;+ const walkCap = historyWalkCap(offset, limit);const raw = await sg.raw('log','--full-history','--author-date-order',`--format=${GIT_LOG_FORMAT}`,+ '-n',+ String(walkCap),...startRefs,'--',okPath,);+ const parsedFolderEntries = parseGitLogOutput(raw);+ const windowSaturated = parsedFolderEntries.length >= walkCap;const okDocPrefix = base ? `${base}/.ok/` : '.ok/';const seen = new Set<string>();const entries: TimelineEntry[] = [];- for (const parsed of parseGitLogOutput(raw)) {+ for (const parsed of parsedFolderEntries) {if (seen.has(parsed.sha)) continue;if (!isFolderArtifactSubject(parsed.message)) continue;const touchesFolderArtifact = parsed.contributors.some((c) =>@@ -567,10 +615,11 @@ export async function getFolderTimeline(entries.push(entry);}const total = entries.length;+ const page = entries.slice(offset, offset + limit);return {- entries: entries.slice(offset, offset + limit),+ entries: page,total,- hasMore: offset + limit < total,+ hasMore: (windowSaturated && page.length > 0) || offset + limit < total,};} catch (e) {console.warn('[timeline] getFolderTimeline failed, returning empty result:', e);diff --git a/packages/server/src/timeline-telemetry.ts b/packages/server/src/timeline-telemetry.tsnew file mode 100644index 000000000..112fc4269--- /dev/null+++ b/packages/server/src/timeline-telemetry.ts@@ -0,0 +1,69 @@+import type { Counter, Histogram } from '@opentelemetry/api';+import { getMeter } from './telemetry.ts';++export type TimelineQueryMode = 'doc' | 'folder';++export type WidthBucket = '0' | '1' | '2-5' | '6-20' | '21-50' | '50+';++export type CommitsBucket = '0' | '1-50' | '51-200' | '201-500' | '500+';++export function widthBucket(n: number): WidthBucket {+ if (n <= 0) return '0';+ if (n === 1) return '1';+ if (n <= 5) return '2-5';+ if (n <= 20) return '6-20';+ if (n <= 50) return '21-50';+ return '50+';+}++export function commitsBucket(n: number): CommitsBucket {+ if (n <= 0) return '0';+ if (n <= 50) return '1-50';+ if (n <= 200) return '51-200';+ if (n <= 500) return '201-500';+ return '500+';+}++let _queryDuration: Histogram | null = null;+let _coalesced: Counter | null = null;++function queryDurationHist(): Histogram {+ _queryDuration ||= getMeter().createHistogram('ok.timeline.query_duration_ms', {+ description:+ 'Wall-clock duration of one history query. Bounded labels: width_bucket (ref fan-out), commits_bucket (commits gathered), capped (depth bound hit), error (the walk threw — e.g. the PRD-6972 git timeout). The error label is what separates a timeout storm from a burst of legitimately-empty docs, both of which otherwise record width/commits 0.',+ unit: 'ms',+ });+ return _queryDuration;+}++function coalescedCounter(): Counter {+ _coalesced ||= getMeter().createCounter('ok.timeline.coalesced_total', {+ description:+ 'History requests served by an in-flight single-flight walk instead of a fresh git walk. Bounded label: mode ∈ {doc, folder}. A high value is the poll-storm / fan-out signal.',+ });+ return _coalesced;+}++export function recordTimelineQuery(event: {+ durationMs: number;+ width: number;+ commits: number;+ capped: boolean;+ error?: boolean;+}): void {+ queryDurationHist().record(Math.max(0, event.durationMs), {+ width_bucket: widthBucket(event.width),+ commits_bucket: commitsBucket(event.commits),+ capped: event.capped,+ error: event.error ?? false,+ });+}++export function recordTimelineCoalesced(mode: TimelineQueryMode): void {+ coalescedCounter().add(1, { mode });+}++export function __resetTimelineTelemetryForTesting(): void {+ _queryDuration = null;+ _coalesced = null;+}