Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok-server): defer boot git housekeeping past ready (PRD-8121) (#3779)
mike-inkeep4cce5ed4761c
diff --git a/.changeset/windows-boot-api-responsiveness.md b/.changeset/windows-boot-api-responsiveness.mdnew file mode 100644index 000000000..0566f7e72--- /dev/null+++ b/.changeset/windows-boot-api-responsiveness.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++The server now answers API requests as soon as it starts instead of staying silent for up to a minute or more on some Windows machines. Boot-time git housekeeping (history-repo gc configuration, rename-log garbage collection, shadow maintenance) used to run before the server declared itself ready, and every API endpoint waited on that; on hosts where antivirus scanning makes each git subprocess launch slow — a common Windows Defender configuration — the housekeeping burst serialized into a 60-90 second window where `ok status` reported the server alive but every request timed out, and MCP clients such as Claude Desktop repeatedly reported the server unreachable right after a restart. The same window also produced spurious "block timeout reached" git errors in the server log. Housekeeping now runs in the background after the server is ready, so requests are served immediately and the housekeeping still completes; shutdown waits for any in-flight housekeeping so it can never race a project teardown.diff --git a/knip.config.ts b/knip.config.tsindex b61debe5e..8ad68f996 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -124,7 +124,9 @@ export default {'packages/server': {entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],project: 'src/**',- ignoreDependencies: ['@types/shell-quote'],+ ignoreDependencies: [+ '@types/shell-quote',+ ],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex d7a845280..dfd95ef49 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,3 +1,4 @@+import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 005627195..8bfdb40cd 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,3 +1,4 @@+import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.tsindex f4cc8a286..2a597ec3d 100644--- a/packages/core/src/bridge/compose.ts+++ b/packages/core/src/bridge/compose.ts@@ -1,3 +1,4 @@+import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';diff --git a/packages/core/src/bridge/divergence-locate.ts b/packages/core/src/bridge/divergence-locate.tsindex 6b505314d..d979f4b39 100644--- a/packages/core/src/bridge/divergence-locate.ts+++ b/packages/core/src/bridge/divergence-locate.ts@@ -1,3 +1,4 @@+import { findFirstDivergenceIndex } from './tolerance-telemetry.ts';export const BRIDGE_LINE_KINDS = [diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 8fb428b90..01ef76a9f 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,3 +1,4 @@+import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsindex 9d9c244b0..463e89595 100644--- a/packages/core/src/bridge/growth-detect.ts+++ b/packages/core/src/bridge/growth-detect.ts@@ -1,3 +1,4 @@+const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.tsindex c43fdd7e7..0939885bb 100644--- a/packages/core/src/bridge/intraline-predicate.ts+++ b/packages/core/src/bridge/intraline-predicate.ts@@ -1,3 +1,4 @@+export function rawLineCounts(doc: string): Map<string, number> {const counts = new Map<string, number>();for (const line of doc.split('\n')) {diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex 251560a35..c0dc65705 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -65,6 +65,7 @@ export function tryLineLevelCombine(return { clean: true, merged };}+export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex 01ac80099..dcc5b0690 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,3 +1,4 @@+import { stripFrontmatter } from '../extensions/frontmatter.ts';import { bodyEdgeEmpties } from './doc-boundary-space.ts';diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.tsindex 754dc5cc2..0be5203e4 100644--- a/packages/core/src/bridge/pm-structural-equivalence.ts+++ b/packages/core/src/bridge/pm-structural-equivalence.ts@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };const BR_LITERAL_RE = /^<br\s*\/?>$/i;+interface DegradeEntry {readonly label: string;readonly severity: ToleranceClassSeverity;@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {ignoreAttrs?: (attrKey: string) => boolean;}+/** Rebuild a node with `fn` applied to each child; identity when childless.* Shared by the degrade canonicalizers so none re-implements the walk. */function mapChildren(@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {return { normalized: current, fired };}+export function comparePmStructural(expected: PmStructuralNode,actual: PmStructuralNode,diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.tsindex af20de1e2..dca644141 100644--- a/packages/core/src/bridge/subsequence.ts+++ b/packages/core/src/bridge/subsequence.ts@@ -1,3 +1,4 @@+/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):* insertions in `haystack` are free; any dropped or substituted `needle` byte* fails. */diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex 83d47404a..a363dfd54 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,3 +1,4 @@+import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.tsindex 9807a7e82..4499dbc92 100644--- a/packages/core/src/markdown/code-fence.ts+++ b/packages/core/src/markdown/code-fence.ts@@ -1,3 +1,4 @@+export function selectFenceChar(info: string): '`' | '~' {return info.includes('`') ? '~' : '`';}diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 7415c474a..34704165b 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex ece5c02a1..b6299a948 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,3 +1,4 @@+import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex 54774764a..acd398aa6 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.tsindex 43ecdc709..ba9b56384 100644--- a/packages/core/src/markdown/div-align-promoter.ts+++ b/packages/core/src/markdown/div-align-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex 6d3f3643e..4513da9bb 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,3 +1,4 @@+const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 00f5771ee..6931623c7 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}+interface GfmExample {section: string;markdown: string;@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}+interface MdxCrashEntry {id: string;input: string;@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}+export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}+export interface NgPinnedCase {id: string;name: string;@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}+export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex 8b1eb8519..daa3ef82b 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,3 +1,4 @@+import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;+function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}+const WORDS = ['lorem','ipsum',@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}+type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}+function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 420dc0fe5..32c055c5b 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,6 +7,7 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';+export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 2653473da..283913255 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,3 +1,4 @@+export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex da0a81d23..5d1000cc4 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex 787315157..9681c0056 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,3 +1,4 @@+import type { Element as HastElement, Root as HastRoot } from 'hast';import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified().use(rehypeParse, { fragment: true });+ const processor = unified()+ .use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 706fa9afb..994eb6917 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,3 +1,4 @@+import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex 779e27500..ec1ac1b7e 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromPmMark,@@ -206,6 +207,7 @@ export class MarkdownManager {}}+const registry = createRegistry();function destructureAttrs(@@ -254,6 +256,7 @@ function destructureAttrs(return result;}+function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecreturn freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;}+function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}+import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(}));}+if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(}));}+if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(};}+const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}+function buildPmToMdastHandlers(schema: Schema,freshness: FreshnessCheckerHolder,diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.tsindex fa0be9e86..b79e9aef7 100644--- a/packages/core/src/markdown/lint/applies-to.ts+++ b/packages/core/src/markdown/lint/applies-to.ts@@ -1,3 +1,4 @@+import picomatch from 'picomatch';import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.tsindex 312c9c74b..94b34dee1 100644--- a/packages/core/src/markdown/lint/config-files.ts+++ b/packages/core/src/markdown/lint/config-files.ts@@ -1,3 +1,4 @@+const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set(['.markdownlint.json','.markdownlint.jsonc',diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.tsindex 1a81aa524..fbbd309df 100644--- a/packages/core/src/markdown/lint/config-schemas.ts+++ b/packages/core/src/markdown/lint/config-schemas.ts@@ -52,6 +52,7 @@ const fullPluginShape = Object.fromEntries(LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),) as z.ZodRawShape;+export const LinterConfigSchema = z.object({enabled: z.boolean(),plugins: z.object(fullPluginShape),diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.tsindex d48eea5e4..a51f2ffb0 100644--- a/packages/core/src/markdown/lint/default-config.ts+++ b/packages/core/src/markdown/lint/default-config.ts@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSettingMD013: false,};+export function resolveMarkdownlintConfig(rules: Record<string, MarkdownlintRuleSetting> | undefined,): Configuration {diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.tsindex ef478e268..9c9542661 100644--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts@@ -1,3 +1,4 @@+import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';export interface FrontmatterFieldConstraint {diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.tsindex 5f953d667..b0e7833fd 100644--- a/packages/core/src/markdown/lint/frontmatter-validate.ts+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts@@ -1,3 +1,4 @@+import Ajv, { type ValidateFunction } from 'ajv';import Ajv2019 from 'ajv/dist/2019.js';import Ajv2020 from 'ajv/dist/2020.js';diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.tsindex 11b5abdfd..ffd277a90 100644--- a/packages/core/src/markdown/lint/index.ts+++ b/packages/core/src/markdown/lint/index.ts@@ -1,3 +1,4 @@+import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';import type { LintDiagnostic } from './types.ts';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts b/packages/core/src/markdown/lint/okf-frontmatter/materialize.tsindex 7a5af097e..f438f1b16 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts@@ -1,3 +1,4 @@+import type { OkfRuleId } from '../okf-rule-meta.ts';import { fileNameFor, OKF_SCHEMA_DIR, okfSchemaPathFor } from './paths.ts';import { OKF_FRONTMATTER_REGISTRY } from './registry.ts';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts b/packages/core/src/markdown/lint/okf-frontmatter/paths.tsindex 1ee913527..c290b6878 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts@@ -1,3 +1,4 @@+import type { OkfRuleId } from '../okf-rule-meta.ts';export const OKF_SCHEMA_DIR = '.ok/okf';diff --git a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts b/packages/core/src/markdown/lint/okf-frontmatter/registry.tsindex f325fbbb4..53ecb619d 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts@@ -1,3 +1,4 @@+import { compileAppliesTo } from '../applies-to.ts';import { validateFrontmatterSource } from '../frontmatter-validate.ts';import {diff --git a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts b/packages/core/src/markdown/lint/okf-frontmatter/schemas.tsindex f1c37671b..89845d3d5 100644--- a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts+++ b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts@@ -1,3 +1,4 @@+// file-level form is deliberate: the sibling `biome-ignore` must sit on the line// oxlint-disable unicorn/no-thenablediff --git a/packages/core/src/markdown/lint/okf-project/rules.ts b/packages/core/src/markdown/lint/okf-project/rules.tsindex 6d691ae2b..8b476332e 100644--- a/packages/core/src/markdown/lint/okf-project/rules.ts+++ b/packages/core/src/markdown/lint/okf-project/rules.ts@@ -1,3 +1,4 @@+import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';diff --git a/packages/core/src/markdown/lint/okf-rule-meta.ts b/packages/core/src/markdown/lint/okf-rule-meta.tsindex 4de50d79f..44913a9dc 100644--- a/packages/core/src/markdown/lint/okf-rule-meta.ts+++ b/packages/core/src/markdown/lint/okf-rule-meta.ts@@ -1,3 +1,4 @@+export const OKF_RULE_IDS = ['no-wiki-links','log-shape',diff --git a/packages/core/src/markdown/lint/okf-rules.ts b/packages/core/src/markdown/lint/okf-rules.tsindex 1d5538421..d0999b62e 100644--- a/packages/core/src/markdown/lint/okf-rules.ts+++ b/packages/core/src/markdown/lint/okf-rules.ts@@ -1,3 +1,4 @@+import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from './okf-rule-meta.ts';import type { OkfRule } from './okf-runner.ts';import { indexShape } from './rules/index-shape.ts';diff --git a/packages/core/src/markdown/lint/okf-runner.ts b/packages/core/src/markdown/lint/okf-runner.tsindex de130e3f4..fabb08d6e 100644--- a/packages/core/src/markdown/lint/okf-runner.ts+++ b/packages/core/src/markdown/lint/okf-runner.ts@@ -1,3 +1,4 @@+import type { Root } from 'mdast';import remarkFrontmatter from 'remark-frontmatter';import remarkGfm from 'remark-gfm';diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.tsindex 09c8450ee..0a089990e 100644--- a/packages/core/src/markdown/lint/plugins.ts+++ b/packages/core/src/markdown/lint/plugins.ts@@ -1,3 +1,4 @@+import { z } from 'zod';import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';import {@@ -23,6 +24,7 @@ import {type OkfSlice,} from './types.ts';+const MarkdownlintRuleSettingSchema = z.union([z.boolean(),z.enum(MARKDOWNLINT_RULE_SEVERITIES),diff --git a/packages/core/src/markdown/lint/rules/index-shape.ts b/packages/core/src/markdown/lint/rules/index-shape.tsindex 59fe9b87d..fcbb1b56c 100644--- a/packages/core/src/markdown/lint/rules/index-shape.ts+++ b/packages/core/src/markdown/lint/rules/index-shape.ts@@ -1,3 +1,4 @@+import type { List, ListItem } from 'mdast';import { EXIT, visit } from 'unist-util-visit';import { defineScopedOkfRule } from '../okf-runner.ts';diff --git a/packages/core/src/markdown/lint/rules/log-shape.ts b/packages/core/src/markdown/lint/rules/log-shape.tsindex e0159519f..431e4e9c8 100644--- a/packages/core/src/markdown/lint/rules/log-shape.ts+++ b/packages/core/src/markdown/lint/rules/log-shape.ts@@ -1,3 +1,4 @@+import type { Heading } from 'mdast';import { toString as headingText } from 'mdast-util-to-string';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/lint/rules/no-wiki-links.ts b/packages/core/src/markdown/lint/rules/no-wiki-links.tsindex 2123e977f..f75a04d15 100644--- a/packages/core/src/markdown/lint/rules/no-wiki-links.ts+++ b/packages/core/src/markdown/lint/rules/no-wiki-links.ts@@ -1,3 +1,4 @@+import type { Point } from 'unist';import { visit } from 'unist-util-visit';import { defineOkfRule } from '../okf-runner.ts';diff --git a/packages/core/src/markdown/lint/rules/reserved-casing.ts b/packages/core/src/markdown/lint/rules/reserved-casing.tsindex 89ef3e4a9..c8b4d8f28 100644--- a/packages/core/src/markdown/lint/rules/reserved-casing.ts+++ b/packages/core/src/markdown/lint/rules/reserved-casing.ts@@ -1,3 +1,4 @@+import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';import { defineOkfRule } from '../okf-runner.ts';diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.tsindex 6836b962d..c04fa4de0 100644--- a/packages/core/src/markdown/lint/types.ts+++ b/packages/core/src/markdown/lint/types.ts@@ -1,3 +1,4 @@+import type { BrokenLinkReason } from '../../schemas/api/agent-write.ts';import type { OkfRuleId } from './okf-rule-meta.ts';@@ -112,6 +113,7 @@ export interface OkfSlice {generate?: { index?: boolean };}+interface RuleOptionSpecBase {key: string;description: string;diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.tsindex 98238656e..437cc539a 100644--- a/packages/core/src/markdown/lint/validation-counts.ts+++ b/packages/core/src/markdown/lint/validation-counts.ts@@ -1,3 +1,4 @@+export interface ValidationSourceCounts {errorCount: number;warningCount: number;diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex a5b511f25..bd79424c7 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex ed89371d0..00fbc0035 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex 8ce2b2492..df788a80d 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,3 +1,4 @@+import type { Element, Root as HastRoot, Text as HastText } from 'hast';import type { Root as MdastRoot, Text as MdastText } from 'mdast';import type { Handler } from 'mdast-util-to-hast';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex bfd7e3109..fa3cfcd86 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 1a897fca8..17ed2b829 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex d988f4b8b..4aa0490c4 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,6 +168,7 @@ export function parseRecursive(}}+interface VFilePlace {offset?: number;start?: { offset?: number };@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}+interface Region {start: number;end: number;@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}+export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}+interface SourceBlock {src: string;start: number;@@ -452,6 +456,7 @@ function tryPerBlockFallback(};}+function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex e6ab4fd57..43d420187 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,3 +1,4 @@+export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex 0e3224206..55736041c 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex 91cdf658f..ccf06e94d 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,3 +1,4 @@+import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';import { isBlankLineParagraph } from './zero-emission-blocks.ts';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex 0f399d34c..e5b4c9eba 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,3 +1,4 @@+import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- } else if (first === '[') {+ }+ else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex db10fa54b..ca225ce9b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,3 +1,4 @@+import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 34068d103..3a2524a9a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 93151d43b..2279a0189 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex 188f02d83..a0f467c42 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4ba2c3418..4e8542a21 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex 1a74b1272..a3c96b24a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex de35e7b79..e95cf43d6 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex b4be1b2ea..ffdb4d5b5 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex 3c8d88b7c..e2a96d1a7 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex cf2c9da8e..0389575ac 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,3 +1,4 @@+import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 4d3250d3a..8be632ba4 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,3 +1,4 @@+export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.tsindex 0dd54070e..96304e7a5 100644--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts@@ -1,3 +1,4 @@+import type { JSONContent } from '@tiptap/core';import type { Nodes } from 'mdast';import { expect } from 'vitest';diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 7cac5b042..93798cf83 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,3 +1,4 @@+import type { Node as PmNode } from '@tiptap/pm/model';import type {MdxJsxAttribute,diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex b012a5aff..8c08b7a04 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,3 +1,4 @@+import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 3e79f8cb6..959cc0bd2 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,3 +1,4 @@+import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.tsindex 0f1b0f27d..6e6d73400 100644--- a/packages/core/src/markdown/underline-promoter.ts+++ b/packages/core/src/markdown/underline-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex 1a082bda7..932d7d2a8 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,3 +1,4 @@+import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex d578476a7..ac9f5239b 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,3 +1,4 @@+const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex 6dad26200..afd9936fe 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {}}+const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {};}+function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};+const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {diff --git a/packages/server/src/boot-shadow-housekeeping-deferral.test.ts b/packages/server/src/boot-shadow-housekeeping-deferral.test.tsnew file mode 100644index 000000000..97fb82c43--- /dev/null+++ b/packages/server/src/boot-shadow-housekeeping-deferral.test.ts@@ -0,0 +1,287 @@+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import simpleGit from 'simple-git';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';++/**+ * Boot-time shadow housekeeping (gc-config writes, rename-log GC/rebuild,+ * shadow maintenance) must not gate `ready`.+ *+ * Each of those legs is a burst of git subprocesses. On hosts where a process+ * spawn is expensive (Windows with AV real-time scanning taxes CreateProcess+ * at ~1s per spawn, on the event-loop thread), the serialized burst held+ * `ready` — and every `/api/*` handler gated on it — hostage for 60-90s after+ * every start, while `ok status` reported the server alive. Per-phase timeout+ * caps around the burst could not bound it, because the same spawn cost+ * starves the timers those caps rely on.+ *+ * Contract pinned here:+ * 1. `ready` settles while ALL THREE housekeeping legs are held open —+ * each leg is blocked independently, so moving ANY of them back into the+ * pre-ready path (not just the first) deadlocks this test on the vitest+ * timeout.+ * 2. Housekeeping still runs after `ready` — deferral must not become+ * deletion. Observed through the real path: every leg is invoked and the+ * gc config lands in the shadow repo's config file.+ */++function makeGate() {+ let release!: () => void;+ const held = new Promise<void>((r) => {+ release = r;+ });+ return { held, release, calls: 0, readyHadSettledAtCall: null as boolean | null };+}++const gates = vi.hoisted(() => {+ const state = {+ readySettled: false,+ gcConfig: null as unknown as ReturnType<typeof makeGate>,+ renameGc: null as unknown as ReturnType<typeof makeGate>,+ maintenance: null as unknown as ReturnType<typeof makeGate>,+ /** When > 0, the gcRenameLog mock consumes one and returns `skipped: true`+ * without forwarding — simulates a runtime GC owning the dedup slot. */+ renameGcSkipFirst: 0,+ };+ return state;+});++// Partial mocks: override only the three housekeeping entry points with+// hold-open gates; everything else stays real. initShadowRepo's own internal+// configureShadowGc call is not intercepted (intra-module reference), but the+// factory passes `deferGcConfig: true`, so the deferred runner is the only+// caller that matters.+vi.mock('./shadow-repo.ts', async (importOriginal) => {+ const actual = await importOriginal<typeof import('./shadow-repo.ts')>();+ return {+ ...actual,+ configureShadowGc: vi.fn(async (shadow: unknown) => {+ gates.gcConfig.calls += 1;+ gates.gcConfig.readyHadSettledAtCall = gates.readySettled;+ await gates.gcConfig.held;+ return actual.configureShadowGc(shadow as Parameters<typeof actual.configureShadowGc>[0]);+ }),+ };+});++vi.mock('./rename-log.ts', async (importOriginal) => {+ const actual = await importOriginal<typeof import('./rename-log.ts')>();+ return {+ ...actual,+ gcRenameLog: vi.fn(async (...args: Parameters<typeof actual.gcRenameLog>) => {+ gates.renameGc.calls += 1;+ gates.renameGc.readyHadSettledAtCall = gates.readySettled;+ if (gates.renameGcSkipFirst > 0) {+ gates.renameGcSkipFirst -= 1;+ return { scanned: 0, dropped: 0, retained: 0, rebuilt: 0, skipped: true };+ }+ await gates.renameGc.held;+ return actual.gcRenameLog(...args);+ }),+ };+});++vi.mock('./maintenance-coordinator.ts', async (importOriginal) => {+ const actual = await importOriginal<typeof import('./maintenance-coordinator.ts')>();+ return {+ ...actual,+ createMaintenanceCoordinator: (+ ...args: Parameters<typeof actual.createMaintenanceCoordinator>+ ) => {+ const coordinator = actual.createMaintenanceCoordinator(...args);+ const originalRun = coordinator.runBootMaintenance.bind(coordinator);+ coordinator.runBootMaintenance = async () => {+ gates.maintenance.calls += 1;+ gates.maintenance.readyHadSettledAtCall = gates.readySettled;+ await gates.maintenance.held;+ return originalRun();+ };+ return coordinator;+ },+ };+});++import { createServer, type ServerInstance } from './server-factory.ts';++describe('createServer() — boot shadow housekeeping is deferred past ready', () => {+ let projectDir: string;+ let server: ServerInstance | null;++ beforeEach(async () => {+ gates.readySettled = false;+ gates.renameGcSkipFirst = 0;+ gates.gcConfig = makeGate();+ gates.renameGc = makeGate();+ gates.maintenance = makeGate();+ projectDir = await mkdtemp(join(tmpdir(), 'ok-boot-housekeeping-'));+ const git = simpleGit(projectDir);+ await git.init(['--initial-branch=main']);+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ await git.raw('commit', '--allow-empty', '-m', 'seed');+ server = null;+ });++ afterEach(async () => {+ // Release every gate before destroy: the destroy path drains the+ // in-flight housekeeping run, which would otherwise hang on a held gate.+ gates.gcConfig.release();+ gates.renameGc.release();+ gates.maintenance.release();+ await server?.destroy().catch(() => {});+ await rm(projectDir, { recursive: true, force: true });+ });++ test('ready settles while all three legs are held; housekeeping then completes', async () => {+ const srv = createServer({+ contentDir: projectDir,+ projectDir,+ quiet: true,+ });+ server = srv;+ void srv.ready.then(() => {+ gates.readySettled = true;+ });++ // With every housekeeping leg blocked indefinitely, ready must still+ // settle. A regression that re-awaits ANY leg pre-ready hangs here and+ // fails on the vitest timeout.+ await srv.ready;++ // Housekeeping is scheduled on a macrotask after ready's microtasks — let+ // the first leg start, then prove ready's settlement never waited on it.+ // Generous ceilings: a loaded CI worker can stretch scheduling latency.+ const wait = { timeout: 10_000, interval: 100 };+ await vi.waitFor(() => {+ expect(gates.gcConfig.calls).toBeGreaterThan(0);+ }, wait);+ expect(gates.gcConfig.readyHadSettledAtCall).toBe(true);++ // Deferral is not deletion: release the gates one at a time and watch+ // each subsequent leg run, post-ready, in order.+ gates.gcConfig.release();+ await vi.waitFor(() => {+ expect(gates.renameGc.calls).toBeGreaterThan(0);+ }, wait);+ expect(gates.renameGc.readyHadSettledAtCall).toBe(true);++ gates.renameGc.release();+ await vi.waitFor(() => {+ expect(gates.maintenance.calls).toBeGreaterThan(0);+ }, wait);+ expect(gates.maintenance.readyHadSettledAtCall).toBe(true);+ gates.maintenance.release();++ // The real configureShadowGc must land the gc config in the shadow repo.+ const shadowGitDir = join(projectDir, '.git', 'ok');+ await vi.waitFor(+ async () => {+ const sg = simpleGit({ timeout: { block: 10_000 } }).env({ GIT_DIR: shadowGitDir });+ const gcAuto = (await sg.raw('config', 'gc.auto')).trim();+ expect(gcAuto).toBe('512');+ },+ { timeout: 15_000, interval: 250 },+ );+ }, 30_000);++ test('the boot rebuild retries past skipped GC passes until one runs', async () => {+ // Simulate a runtime GC owning the per-gitDir dedup slot for the first+ // two boot-rebuild attempts. The loop must retry through them and land+ // the third call, not mistake a dropped pass for success.+ gates.renameGcSkipFirst = 2;+ gates.gcConfig.release();+ gates.renameGc.release();+ gates.maintenance.release();++ const srv = createServer({+ contentDir: projectDir,+ projectDir,+ quiet: true,+ });+ server = srv;+ await srv.ready;++ // Two skipped attempts (1s spacing) + the real third call.+ await vi.waitFor(+ () => {+ expect(gates.renameGc.calls).toBe(3);+ },+ { timeout: 15_000, interval: 100 },+ );+ // The chain proceeded past the retry loop to the maintenance leg.+ await vi.waitFor(+ () => {+ expect(gates.maintenance.calls).toBeGreaterThan(0);+ },+ { timeout: 10_000, interval: 100 },+ );+ }, 30_000);++ test('an exhausted rebuild retry budget logs, gives up, and the chain continues', async () => {+ const prevInterval = process.env.OK_BOOT_RENAME_GC_RETRY_INTERVAL_MS;+ process.env.OK_BOOT_RENAME_GC_RETRY_INTERVAL_MS = '10';+ try {+ // Every attempt is swallowed by the dedup slot: the loop must stop at+ // its 30-attempt budget (not spin forever) and still reach the+ // maintenance leg rather than aborting the chain.+ gates.renameGcSkipFirst = Number.MAX_SAFE_INTEGER;+ gates.gcConfig.release();+ gates.renameGc.release();++ const srv = createServer({+ contentDir: projectDir,+ projectDir,+ quiet: true,+ });+ server = srv;+ await srv.ready;++ await vi.waitFor(+ () => {+ expect(gates.maintenance.calls).toBeGreaterThan(0);+ },+ { timeout: 15_000, interval: 100 },+ );+ expect(gates.renameGc.calls).toBe(30);+ gates.maintenance.release();+ } finally {+ if (prevInterval === undefined) delete process.env.OK_BOOT_RENAME_GC_RETRY_INTERVAL_MS;+ else process.env.OK_BOOT_RENAME_GC_RETRY_INTERVAL_MS = prevInterval;+ }+ }, 30_000);++ test('destroy() while the first leg is held stays bounded and cancels the later legs', async () => {+ const srv = createServer({+ contentDir: projectDir,+ projectDir,+ quiet: true,+ destroyTimeoutMs: 1_500,+ });+ server = srv;+ await srv.ready;++ // Let the first leg start and hold it open — a wedged git subprocess.+ await vi.waitFor(+ () => {+ expect(gates.gcConfig.calls).toBeGreaterThan(0);+ },+ { timeout: 10_000, interval: 100 },+ );++ // destroy() must not hang on the held leg: the drain races+ // destroyTimeoutMs and abandons. The closed flag set by the drain then+ // cancels the not-yet-started legs when the held leg is finally released.+ await srv.destroy();+ server = null;+ expect(gates.renameGc.calls).toBe(0);+ expect(gates.maintenance.calls).toBe(0);++ gates.gcConfig.release();+ // Give the abandoned runner a beat: even once released, the closed flag+ // must keep the later legs from starting.+ await new Promise((r) => setTimeout(r, 250));+ expect(gates.renameGc.calls).toBe(0);+ expect(gates.maintenance.calls).toBe(0);+ }, 30_000);+});diff --git a/packages/server/src/file-watcher-chokidar-fallback.test.ts b/packages/server/src/file-watcher-chokidar-fallback.test.tsindex 71dea9702..70e3db712 100644--- a/packages/server/src/file-watcher-chokidar-fallback.test.ts+++ b/packages/server/src/file-watcher-chokidar-fallback.test.ts@@ -98,7 +98,13 @@ describe('chokidar backend — live subfolder watching (forceBackend)', () => {await rm(tmpDir, { recursive: true, force: true });});- async function until(predicate: () => boolean, timeoutMs = 4000): Promise<boolean> {+ // The ceiling only bounds failure detection — `until` returns the moment the+ // predicate holds, so a healthy run never waits it out. It needs headroom+ // for a fully loaded runner: with every package's test workers plus the+ // servers' post-ready background git housekeeping sharing the machine,+ // chokidar's dispatch latency can blow well past a few seconds while the+ // watcher itself is working correctly.+ async function until(predicate: () => boolean, timeoutMs = 15_000): Promise<boolean> {const deadline = Date.now() + timeoutMs;while (Date.now() < deadline) {if (predicate()) return true;diff --git a/packages/server/src/maintenance-coordinator.test.ts b/packages/server/src/maintenance-coordinator.test.tsindex bd52b53c4..2a3fc58e3 100644--- a/packages/server/src/maintenance-coordinator.test.ts+++ b/packages/server/src/maintenance-coordinator.test.ts@@ -301,21 +301,33 @@ describe('MaintenanceCoordinator triggers (PRD-6972 FR4 / D8 / D12)', () => {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;- // Returned at the cap, not after the (still-pending) maintenance run.- expect(elapsed).toBeLessThan(2000);- resolveMaintenance(); // let the background run settle so it does not dangle+ test('runBootMaintenance settles only after the whole maintenance run', async () => {+ // The settlement IS the shutdown-drain guarantee: destroy() awaits this+ // promise before content-dir teardown, so settling while work continued+ // in the background (the old capped behavior) would let a maintenance git+ // subprocess race the removal of `.git/ok`.+ vi.useFakeTimers();+ try {+ const coord = createMaintenanceCoordinator({ getShadow: () => shadow });+ let resolveMaintenance: () => void = () => {};+ spyScheduledMaintenance(coord).mockImplementation(+ () =>+ new Promise<void>((res) => {+ resolveMaintenance = () => res();+ }),+ );+ let settled = false;+ const run = coord.runBootMaintenance().then(() => {+ settled = true;+ });+ await vi.advanceTimersByTimeAsync(1_200);+ expect(settled).toBe(false);+ resolveMaintenance();+ await run;+ expect(settled).toBe(true);+ } finally {+ vi.useRealTimers();+ }});test('runBootMaintenance no-ops when maintenance is disabled', async () => {@@ -324,11 +336,47 @@ describe('MaintenanceCoordinator triggers (PRD-6972 FR4 / D8 / D12)', () => {try {const coord = createMaintenanceCoordinator({ getShadow: () => shadow });const spy = spyScheduledMaintenance(coord);- await coord.runBootMaintenance(50);+ await coord.runBootMaintenance();expect(spy).toHaveBeenCalledTimes(0);} finally {if (prev === undefined) delete process.env.OK_SHADOW_MAINTENANCE_DISABLED;else process.env.OK_SHADOW_MAINTENANCE_DISABLED = prev;}});++ test('a destroy() mid-run stops the compound run at the next leg boundary', async () => {+ const coord = createMaintenanceCoordinator({+ getShadow: () => shadow,+ projectGitDir: resolve(projectRoot, '.git'),+ });+ // Hold the FIRST leg (consolidation) open, destroy while it runs, then+ // release — the reap and gc legs must not start.+ let releaseConsolidate: () => void = () => {};+ const consolidateSpy = vi+ .spyOn(+ coord as unknown as { consolidateInner: (trigger: string) => Promise<void> },+ 'consolidateInner',+ )+ .mockImplementation(+ () =>+ new Promise<void>((res) => {+ releaseConsolidate = () => res();+ }),+ );+ const reapSpy = vi+ .spyOn(coord as unknown as { reapInner: (trigger: string) => Promise<void> }, 'reapInner')+ .mockResolvedValue(undefined);+ const gcSpy = vi+ .spyOn(coord as unknown as { gcInner: (trigger: string) => Promise<void> }, 'gcInner')+ .mockResolvedValue(undefined);++ const run = coord.runBootMaintenance();+ await new Promise((r) => setTimeout(r, 10));+ expect(consolidateSpy).toHaveBeenCalledTimes(1);+ coord.destroy();+ releaseConsolidate();+ await run;+ expect(reapSpy).not.toHaveBeenCalled();+ expect(gcSpy).not.toHaveBeenCalled();+ });});diff --git a/packages/server/src/maintenance-coordinator.ts b/packages/server/src/maintenance-coordinator.tsindex cdd402076..f29c62aa8 100644--- a/packages/server/src/maintenance-coordinator.ts+++ b/packages/server/src/maintenance-coordinator.ts@@ -167,27 +167,18 @@ export class MaintenanceCoordinator {}/**- * Boot maintenance: time-capped (default ≤ 1s of boot blocking) with- * background continuation for a large backlog, mirroring the existing boot-GC- * `Promise.race` precedent. The op keeps running after the cap; we only stop- * AWAITING it so boot proceeds.+ * Boot maintenance. Awaits the WHOLE compound run — no time cap, no+ * background continuation. The caller (the server's deferred shadow+ * housekeeping) already runs off the readiness path, and its shutdown drain+ * awaits this promise; a capped variant that let work continue past its+ * settlement made that drain a false guarantee, so the destroy → content-dir+ * removal path could race a still-running maintenance git subprocess+ * (ENOTEMPTY on `.git/ok`). A run interrupted by `destroy()` stops at the+ * next leg boundary (see `runScheduledMaintenance`).*/- async runBootMaintenance(capMs = 1000): Promise<void> {+ async runBootMaintenance(): 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);- // Background continuation — the inner legs each catch their own errors, so a- // rejection here is an unexpected path. Log it (rather than swallowing) so a- // rare late failure after boot moved on stays diagnosable, while still- // preventing it from surfacing as an unhandled rejection.- void work.catch((err) => {- log.warn({ err }, '[shadow-maintenance] boot maintenance background continuation failed');- });+ await this.runScheduledMaintenance('boot');}/**@@ -213,8 +204,12 @@ export class MaintenanceCoordinator {if (this.running) return;this.running = true;try {+ // Re-check destroyed at each leg boundary: a shutdown drain awaiting+ // this run should wait out at most the current leg, not all three.await this.consolidateInner(trigger);+ if (this.destroyed) return;await this.reapInner(trigger);+ if (this.destroyed) return;await this.gcInner(trigger);} finally {this.running = false;diff --git a/packages/server/src/rename-log.test.ts b/packages/server/src/rename-log.test.tsindex e51bec9e6..2e3b1d167 100644--- a/packages/server/src/rename-log.test.ts+++ b/packages/server/src/rename-log.test.ts@@ -1714,5 +1714,10 @@ describe('gcRenameLog concurrency dedup (Finding 4)', () => {expect(skipped.scanned).toBe(0);expect(skipped.dropped).toBe(0);expect(skipped.retained).toBe(0);+ // The dropped invocation self-identifies, so a caller whose options+ // matter (the boot rebuild pass) can retry instead of mistaking the+ // drop for a real all-zero run.+ expect(skipped.skipped).toBe(true);+ expect(real.skipped).toBeUndefined();});});diff --git a/packages/server/src/rename-log.ts b/packages/server/src/rename-log.tsindex 2003e7500..71a08d2a8 100644--- a/packages/server/src/rename-log.ts+++ b/packages/server/src/rename-log.ts@@ -1168,6 +1168,14 @@ interface RenameLogGcResult {dropped: number;retained: number;rebuilt: number;+ /**+ * True when this invocation was dropped by the per-gitDir dedup because+ * another GC pass owned the slot. Distinguishable from a real all-zero run+ * so a caller whose options MATTER (the boot `{rebuild: true}` pass — the+ * only reconstruction opportunity of the session) can retry instead of+ * mistaking the drop for success.+ */+ skipped?: boolean;}export async function gcRenameLog(@@ -1183,7 +1191,7 @@ export async function gcRenameLog(// is never legitimate contention — skipping the second invocation is// always safe; the first pass's reachability set is at least as fresh.if (gcPending.has(shadow.gitDir)) {- return result;+ return { ...result, skipped: true };}gcPending.add(shadow.gitDir);try {diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 3c82902b5..a307f2969 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -236,6 +236,7 @@ import {import { shadowOpGateFor } from './shadow-op-gate.ts';import {commitUpstreamImport,+ configureShadowGc,destroyShadowRepo,initShadowRepo,OK_GENERATOR_WRITER,@@ -1426,6 +1427,151 @@ export function createServer(options: ServerOptions): ServerInstance {});}+ // ── Deferred boot-time shadow housekeeping ────────────────────────────────+ // gc-config writes, the rename-log GC/rebuild, and shadow maintenance are+ // git-subprocess bursts with no data the readiness gate needs. They used to+ // run inside initAsync, which holds `ready` — and every `/api/*` handler+ // gated on it — hostage: on hosts where each git spawn costs ~1s (Windows+ // with AV scanning taxing CreateProcess), the serialized burst kept the API+ // unresponsive for 60-90s after every start, and the per-phase Promise.race+ // caps could not save it because spawn cost lands on the event-loop thread,+ // so the cap timers themselves fire late. Housekeeping now runs after+ // `resolveReady()`, mirroring `deferBootIndexSweep`. Ordering within the+ // run is load-bearing: rename-log GC before maintenance (they share the+ // shadow; maintenance gc packs what the rename GC may rewrite), matching+ // the old in-boot order. Runtime-safety of running post-ready: gcRenameLog+ // serializes per gitDir and preserves in-flight (empty-commitSha) entries,+ // and the maintenance coordinator skips-if-busy and checks `destroyed`.+ let shadowHousekeepingImmediate: NodeJS.Immediate | undefined;+ let shadowHousekeepingInFlight: Promise<void> | undefined;+ let shadowHousekeepingClosed = false;+ let bootRenameLogIndex: ReturnType<typeof loadRenameLogIndex> | null = null;++ async function runShadowHousekeeping(): Promise<void> {+ const shadow = shadowRef.current;+ if (!shadow || shadowHousekeepingClosed) return;+ // Start/finish marks: this is the burst whose serialized latency used to+ // gate readiness, so its post-ready duration is the number that answers+ // "why was the API sluggish for the first N seconds after start".+ const startedAtMono = performance.now();+ log.info({ gitDir: shadow.gitDir }, '[shadow-housekeeping] deferred boot housekeeping started');+ try {+ await configureShadowGc(shadow);+ } catch (e) {+ log.warn({ err: e }, 'failed to write gc config (non-fatal)');+ }+ if (shadowHousekeepingClosed) return;+ if (bootRenameLogIndex) {+ // Reachability GC + rebuild from `OkActorEntry.previous_paths` is+ // best-effort repair — a failure must not undo the already-published+ // index. Until this completes, entries lost from the JSONL are absent+ // from rename history; runtime lookups fall through to lazy disk reads.+ //+ // Retry on `skipped`: now that this runs post-ready, a live-traffic GC+ // pass (Save Version, hard-cap GC, session close) can own the per-gitDir+ // dedup slot when we arrive — and only THIS call carries+ // `{rebuild: true}`, so treating the drop as success would silently+ // skip the session's one reconstruction pass. Bounded: an exhausted+ // retry budget just defers the rebuild to the next boot.+ try {+ const RETRY_BUDGET = 30;+ // Env override exists so a test can force retry exhaustion without+ // 29 seconds of real sleeps; production uses the 1s default.+ const retryIntervalMs =+ Number.parseInt(process.env.OK_BOOT_RENAME_GC_RETRY_INTERVAL_MS ?? '', 10) || 1_000;+ let rebuilt = false;+ for (let attempt = 0; attempt < RETRY_BUDGET; attempt++) {+ const gc = await gcRenameLog(shadow, bootRenameLogIndex, { rebuild: true });+ if (!gc.skipped) {+ rebuilt = true;+ break;+ }+ if (attempt === RETRY_BUDGET - 1) break;+ await new Promise((r) => {+ setTimeout(r, retryIntervalMs).unref?.();+ });+ if (shadowHousekeepingClosed) return;+ }+ if (!rebuilt) {+ log.warn(+ { gitDir: shadow.gitDir },+ '[rename-log] deferred boot GC/rebuild retry budget exhausted (persistent GC contention); rebuild deferred to next boot',+ );+ }+ } catch (e) {+ log.warn(+ { err: e, gitDir: shadow.gitDir },+ '[rename-log] deferred boot GC/rebuild failed; index loaded without GC',+ );+ }+ }+ if (shadowHousekeepingClosed) return;+ try {+ await maintenanceCoordinator?.runBootMaintenance();+ } catch (e) {+ log.warn({ err: e }, '[shadow-maintenance] boot maintenance failed (non-fatal)');+ }+ log.info(+ { gitDir: shadow.gitDir, durationMs: Math.round(performance.now() - startedAtMono) },+ '[shadow-housekeeping] deferred boot housekeeping complete',+ );+ }++ function deferShadowHousekeeping(): void {+ if (shadowHousekeepingClosed) return;+ shadowHousekeepingImmediate = setImmediate(() => {+ shadowHousekeepingImmediate = undefined;+ // Defensive .catch(): every leg catches its own errors, but that+ // guarantee is convention across the runner's body, not type-level —+ // and a late rejection on a drain-abandoned promise would surface as+ // an unhandled rejection mid-shutdown.+ shadowHousekeepingInFlight = runShadowHousekeeping().catch((err) => {+ log.error({ err }, '[shadow-housekeeping] unexpected uncaught failure');+ });+ });+ }++ /**+ * Cancel queued housekeeping and DRAIN the in-flight run. The drain is the+ * load-bearing half: configureShadowGc and gcRenameLog spawn git against+ * the shadow gitDir outside the shadow op gate, so a destroy that returned+ * while a leg was mid-subprocess would race the caller's content-dir+ * removal — the subprocess re-creates `.git/ok` inside the tree being+ * removed and the walk fails ENOTEMPTY. Completeness depends on every leg+ * being awaited to completion inside runShadowHousekeeping — a leg that+ * settles while its work continues in the background re-opens the race+ * (which is why runBootMaintenance is uncapped). The closed flag plus the+ * coordinator's own leg-boundary destroyed-checks keep the await short:+ * the current leg finishes, everything after it is skipped.+ */+ async function closeShadowHousekeeping(): Promise<void> {+ shadowHousekeepingClosed = true;+ if (shadowHousekeepingImmediate !== undefined) {+ clearImmediate(shadowHousekeepingImmediate);+ shadowHousekeepingImmediate = undefined;+ }+ if (!shadowHousekeepingInFlight) return;+ // Bounded to destroyTimeoutMs like every sibling drain in destroy(): a+ // wedged git subprocess must not hang shutdown. On timeout the drain is+ // abandoned (accepting the same narrow teardown-race window the sibling+ // drains accept) and this REJECTS, so the caller records it in the+ // shutdown phaseErrors summary instead of it passing silently.+ let timer: ReturnType<typeof setTimeout> | undefined;+ const timedOut = new Promise<'timeout'>((r) => {+ timer = setTimeout(() => r('timeout'), destroyTimeoutMs);+ });+ try {+ const outcome = await Promise.race([shadowHousekeepingInFlight, timedOut]);+ if (outcome === 'timeout') {+ throw new Error(+ `shadow housekeeping drain timed out after ${destroyTimeoutMs}ms — abandoning in-flight housekeeping`,+ );+ }+ } finally {+ if (timer !== undefined) clearTimeout(timer);+ }+ }+function kickIndexRegeneration(): void {if (indexRegenerationClosed || !indexRegenerationReady || !hasPendingIndexRegeneration()) {return;@@ -3732,6 +3878,29 @@ export function createServer(options: ServerOptions): ServerInstance {log.warn({ err }, '[server] failed to mark server.lock draining');}+ // Flip the maintenance gate BEFORE draining housekeeping: the drain may+ // be awaiting `runBootMaintenance`, whose compound run only stops at the+ // next leg boundary once the coordinator observes `destroyed`. Flipping+ // it after the drain (where the flush-phase comment used to live) left+ // those leg-boundary checks dead for the entire drain, so it awaited+ // all three legs instead of at most the current one. The gate also+ // keeps any later flush-counter / session-close trigger from starting+ // a NEW maintenance op during the flush phases below. Runs AFTER the+ // draining announcement above so a slow drain (bounded at+ // destroyTimeoutMs) never delays readers learning we're going down.+ maintenanceCoordinator?.destroy();++ // Cancel queued deferred shadow housekeeping and drain the in-flight+ // run before any teardown that removes or releases the shadow. A+ // drain timeout rejects so it lands in the shutdown phaseErrors+ // summary rather than passing silently.+ try {+ await closeShadowHousekeeping();+ } catch (err) {+ log.warn({ err }, '[shadow-housekeeping] shutdown drain failed');+ phaseErrors.push({ phase: 'shadow-housekeeping-drain', error: String(err) });+ }+// Flush the removal journal synchronously — a tombstone recorded just// before shutdown must survive the restart or a reconnecting stale// client resurrects the doc. Failure feeds `phaseErrors`: this flush is@@ -3778,13 +3947,9 @@ export function createServer(options: ServerOptions): ServerInstance {// Capture after ready so the count reflects documents loaded during initconst documentCount = hocuspocus.documents.size;- // Stop the maintenance coordinator FIRST, before any flush phase. A- // background gc/consolidation — fired by the flush-counter during the L1/L2- // drains, or by a session-close during the agent-session drain — would- // otherwise race the final commit flush against the same shadow repo.- // `destroy()` flips the gate so no NEW maintenance op starts; combined with- // the single-op gate, the shutdown flush then has the repo to itself.- maintenanceCoordinator?.destroy();+ // The maintenance coordinator was already destroyed in the prologue+ // above (before the housekeeping drain), so no background+ // gc/consolidation can race the flush phases below against the shadow.try {try {@@ -4066,10 +4231,12 @@ export function createServer(options: ServerOptions): ServerInstance {);}- // Auto-initialize shadow repo if not provided+ // Auto-initialize shadow repo if not provided. gc-config writes are+ // deferred into `runShadowHousekeeping` (post-ready) — they are per-boot+ // idempotent housekeeping, not something readiness depends on.if (!shadowRef.current) {try {- shadowRef.current = await initShadowRepo(projectDir);+ shadowRef.current = await initShadowRepo(projectDir, { deferGcConfig: true });log.info({ gitDir: shadowRef.current.gitDir },`[server] history repo initialized at ${shadowRef.current.gitDir}`,@@ -4084,17 +4251,20 @@ export function createServer(options: ServerOptions): ServerInstance {// 1) load the JSONL into the in-memory index (load failure → no index// published; runtime calls fall through to lazy disk reads);// 2) sweep mid-rename-crash orphans (load+sweep are critical — they- // prepare the index for runtime use);+ // prepare the index for runtime use, and the GC's preserve-in-flight+ // rule assumes this boot-time sweep already ran);// 3) publish the index (setRenameLogIndex) BEFORE GC so a GC failure- // doesn't leave the cache empty;- // 4) run reachability GC + rebuild from `OkActorEntry.previous_paths`- // as best-effort — its failure must not undo the loaded index.+ // doesn't leave the cache empty.+ // The git-heavy tail — reachability GC + rebuild, then shadow+ // maintenance — runs in `runShadowHousekeeping` after `ready` settles,+ // never here: it is exactly the git-spawn burst that made boot gate the+ // HTTP API for 60-90s on slow-spawn hosts.if (shadowRef.current) {- let renameLogIndex: ReturnType<typeof loadRenameLogIndex> | null = null;try {- renameLogIndex = loadRenameLogIndex(shadowRef.current.gitDir);+ const renameLogIndex = loadRenameLogIndex(shadowRef.current.gitDir);sweepLazyPopOrphans(shadowRef.current.gitDir, renameLogIndex);setRenameLogIndex(shadowRef.current.gitDir, renameLogIndex);+ bootRenameLogIndex = renameLogIndex;log.info({ entries: renameLogIndex.byTo.size },`[server] rename log loaded (${renameLogIndex.byTo.size} entries)`,@@ -4105,38 +4275,6 @@ export function createServer(options: ServerOptions): ServerInstance {'[rename-log] boot-time load/sweep failed; rename history unavailable',);}- if (renameLogIndex) {- // Wall-clock cap on boot-time GC. The internal git invocations have- // their own per-call timeouts (`OK_GIT_TIMEOUT_MS`), but a corrupt or- // lock-contended shadow repo could still chain timeouts and stall the- // server boot for tens of seconds. Boot must remain bounded — a slow- // GC defers to the next iteration's GC trigger rather than blocking- // the editor from coming online.- const BOOT_GC_TIMEOUT_MS = 10_000;- try {- await Promise.race([- gcRenameLog(shadowRef.current, renameLogIndex, { rebuild: true }),- new Promise<never>((_, reject) =>- setTimeout(- () => reject(new Error(`boot-time GC exceeded ${BOOT_GC_TIMEOUT_MS}ms`)),- BOOT_GC_TIMEOUT_MS,- ),- ),- ]);- } catch (e) {- log.warn({ err: e }, '[rename-log] boot-time GC/rebuild failed; index loaded without GC');- }- }-- // Shadow-repo maintenance at boot. Time-capped to ≤ ~1s of- // boot blocking; a large backlog packs in the background after the cap so- // existing degraded repos heal on first boot post-upgrade. Runs after the- // rename-log GC (shares the shadow); gated + off the write path.- try {- await maintenanceCoordinator?.runBootMaintenance();- } catch (e) {- log.warn({ err: e }, '[shadow-maintenance] boot maintenance failed (non-fatal)');- }}// Verify history repo integrity — reinit only on structural corruption, not transient errors@@ -4149,7 +4287,9 @@ export function createServer(options: ServerOptions): ServerInstance {if (msg.includes('not a git repository') || msg.includes('invalid object')) {log.warn({}, '[server] history repo appears corrupted — reinitializing');try {- shadowRef.current = await initShadowRepo(projectDir);+ // Same deferral as the primary init above: the deferred+ // housekeeping runner owns the gc-config write for the new handle.+ shadowRef.current = await initShadowRepo(projectDir, { deferGcConfig: true });} catch (e2) {log.error({ err: e2 }, '[server] history repo reinit failed');shadowRef.current = undefined;@@ -5519,6 +5659,7 @@ export function createServer(options: ServerOptions): ServerInstance {// observe readiness without paying synchronous planner cost.resolveReady();deferBootIndexSweep();+ deferShadowHousekeeping();},(err) => {indexRegenerationClosed = true;diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.tsindex 2249f7570..41a5d5367 100644--- a/packages/server/src/shadow-repo.ts+++ b/packages/server/src/shadow-repo.ts@@ -221,7 +221,21 @@ export async function enumerateWipChains(* worktree on its first boot post-upgrade will not see the legacy dir at the* common-dir location until the user next boots OK in the main worktree.*/-export async function initShadowRepo(projectRoot: string): Promise<ShadowHandle> {+export async function initShadowRepo(+ projectRoot: string,+ opts?: {+ /**+ * Skip the every-boot `configureShadowGc` call so the caller can run it+ * off the readiness-critical path. Each config write is one git spawn;+ * on hosts where process spawn is expensive (Windows AV scanning ~1s per+ * spawn), these four spawns are pure added latency to a boot sequence+ * that gates the HTTP API. Callers that pass this MUST schedule+ * `configureShadowGc` themselves — the gc config is what keeps a+ * long-lived shadow repo from degrading.+ */+ deferGcConfig?: boolean;+ },+): Promise<ShadowHandle> {// Path resolution lives in @inkeep/open-knowledge-core so the CLI read path// and this server write path use exactly the same rule.const shadowDir = resolveShadowDir(projectRoot);@@ -259,10 +273,12 @@ export async function initShadowRepo(projectRoot: string): Promise<ShadowHandle>// Write gc config on every boot (idempotent) so an existing degraded repo// picks it up post-upgrade, not only freshly-initialized ones.// Best-effort: a config failure must never block boot or the writer lock.- try {- await configureShadowGc(handle);- } catch (e) {- log.warn({ err: e }, 'failed to write gc config (non-fatal)');+ if (!opts?.deferGcConfig) {+ try {+ await configureShadowGc(handle);+ } catch (e) {+ log.warn({ err: e }, 'failed to write gc config (non-fatal)');+ }}// Allowlist-based sweep of legacy WIP refs on every start.