Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.ts
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 = z
entries: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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): MountMcpAndApiHandl
sessionManager,
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.ts
index 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): Persis
const 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): Persis
try {
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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 checkpoint
maxExternalChangeRescue: 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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;
+}