Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Answer busy local agent writes once saved (part of PRD-7398) (#5844)

Andrew Mikofalvy5b1246019bc8
diff --git a/.changeset/busy-project-agent-writes.md b/.changeset/busy-project-agent-writes.md
new file mode 100644
index 000000000..444a065d9
--- /dev/null
+++ b/.changeset/busy-project-agent-writes.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Agent writes to a busy local project now answer as soon as they are saved, carrying a `link-check-deferred` warning when link checks were skipped. A write refused because the project is overloaded now says that nothing was saved, so it is safe to retry.
diff --git a/docs/content/advanced/content-rules/overview.mdx b/docs/content/advanced/content-rules/overview.mdx
index b70182231..66c22a21d 100644
--- a/docs/content/advanced/content-rules/overview.mdx
+++ b/docs/content/advanced/content-rules/overview.mdx
@@ -242,7 +242,7 @@ Every write response carries validation findings for the document it touched, on
**`warnings`** carries up to 10 findings across the whole validation plane — lint violations and broken links alike, honoring the project's `validation.links` setting and, for a reserved log, the **Ignore broken links in log.md** switch. Positions are 1-based (`line`/`column`), ready to echo back to a human, and a `links` finding adds `linkTarget`. The field is present only when the write produced findings.
-**`brokenLinks`** is the dedicated link channel, and unlike `warnings` it is **always present**. An empty array is the positive "every outbound link resolves" confirmation, which saves a separate `links({ kind: "dead" })` round-trip, as long as no `brokenLinkSuppression` sits beside it and `warnings` carries no `link-check-deferred` entry. That entry means the server was still building its link index after starting, so link checks were skipped. That document's links are checked again only when it is written or edited after startup finishes, or by an `audit`, which waits for startup and can time out until then. Each entry names the href exactly as authored, so an agent can grep for it. `reason` is `no-such-doc` (resolved to a docName that doesn't exist), `no-such-file` (a linked asset or source file missing from disk), `excluded` (the file exists on disk but a `.gitignore` or `.okignore` rule keeps it out of the project; a `!` rule in `.okignore`, such as `!ignored/`, re-includes it or its folder), or `unresolvable` (an empty href, or a relative path escaping the content root); `resolvedTo` is `null` for `unresolvable`.
+**`brokenLinks`** is the dedicated link channel, and unlike `warnings` it is **always present**. An empty array is the positive "every outbound link resolves" confirmation, which saves a separate `links({ kind: "dead" })` round-trip, as long as no `brokenLinkSuppression` sits beside it and `warnings` carries no `link-check-deferred` entry. That entry means link checks were skipped, either because the server was still building its link index after starting or because the index was busy with other writes. That document's links are checked again only when it is written or edited later, or by an `audit`, which waits for startup and can time out while the server is still starting. Each entry names the href exactly as authored, so an agent can grep for it. `reason` is `no-such-doc` (resolved to a docName that doesn't exist), `no-such-file` (a linked asset or source file missing from disk), `excluded` (the file exists on disk but a `.gitignore` or `.okignore` rule keeps it out of the project; a `!` rule in `.okignore`, such as `!ignored/`, re-includes it or its folder), or `unresolvable` (an empty href, or a relative path escaping the content root); `resolvedTo` is `null` for `unresolvable`.
**`brokenLinkSuppression`** is present only when the project's reserved-log policy kept findings out of `brokenLinks`, which is what makes an empty array conditional rather than a clean bill of health:
diff --git a/docs/content/reference/agentic-search.mdx b/docs/content/reference/agentic-search.mdx
index 1785e4995..6328112ad 100644
--- a/docs/content/reference/agentic-search.mdx
+++ b/docs/content/reference/agentic-search.mdx
@@ -240,7 +240,7 @@ set("ok");
</script>
```
-`brokenLinks` comes back on every write and edit (empty when they all resolve, unless a `brokenLinkSuppression` beside it reports that the project's reserved-log policy withheld some, or a `link-check-deferred` warning reports that the server was still starting and checked nothing yet), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills/index.mdx) teach the conventions, and the write path enforces the connective tissue.
+`brokenLinks` comes back on every write and edit (empty when they all resolve, unless a `brokenLinkSuppression` beside it reports that the project's reserved-log policy withheld some, or a `link-check-deferred` warning reports that nothing was checked yet because the server was still starting or was busy with other writes), so the agent needs a follow-up dead-link check only after that warning. A brand-new doc nothing points to usually comes back flagged as an orphan with a hub to link it from, but a busy server can skip that hint, so a missing hint does not prove the doc is linked. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills/index.mdx) teach the conventions, and the write path enforces the connective tissue.
## The index is authored, not extracted
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index a9fe22003..7773736ac 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -48,7 +48,7 @@ The write verbs nest their result under the same target key you wrote, mirroring
## Advisory warnings
-`write` and `edit` results may carry a `warnings` array on the document entry (per entry for a batch); `restore_version` carries it at the top level. Entries are discriminated by `kind`. `content-divergence` and `disk-edit-reconciled` are write-integrity signals — the stored doc differs from what the call composed, so re-read it before editing further. `mermaid-parse-error` means the write landed but that fence won't render — fix the fence and re-edit. `lint-violation` reports a content-rule finding at a line and column. `link-check-deferred` means the server was still building its link index after starting, so links were not checked and an empty `brokenLinks` is not an all-clear; that document's links are checked again only when it is written or edited after startup finishes, or by an `audit`, which can time out until then.
+`write` and `edit` results may carry a `warnings` array on the document entry (per entry for a batch); `restore_version` carries it at the top level. Entries are discriminated by `kind`. `content-divergence` and `disk-edit-reconciled` are write-integrity signals — the stored doc differs from what the call composed, so re-read it before editing further. `mermaid-parse-error` means the write landed but that fence won't render — fix the fence and re-edit. `lint-violation` reports a content-rule finding at a line and column. `link-check-deferred` means the server was still building its link index after starting, or the index was busy with other writes, so links were not checked and an empty `brokenLinks` is not an all-clear; that document's links are checked again only when it is written or edited later, or by an `audit`, which can time out until startup finishes.
`delete`, `move` and `install` on a `skill` target carry a separate `warnings` array of plain strings, not `kind`-discriminated entries. It reports work that did not undo the operation: bookkeeping records the server could not update after the skill itself was already deleted, renamed or moved, and — on a delete — that the directory removed was one an earlier failed move had retained for recovery. The operation succeeded; the warning names what to check or repair.
@@ -98,6 +98,8 @@ A write refused because the document's duplication baseline could not be read at
A whole-document replace attempted while another writer changed the same document in the last few seconds returns `urn:ok:error:concurrent-overwrite-refused` (409): nothing was written, so there is no partial edit to undo. This is not tracked conflict state, so there is nothing to resolve. A single-document HTTP response carries `retryAfterSeconds` alongside a matching `Retry-After` header, and the `write` tool appends the same bound to its error text (`Retry after 3s.`). `POST /api/agent-write-batch` keeps its `200` success envelope; each refused entry carries the problem type and `retryAfterSeconds`, while sibling entries are unaffected. Wait that long and repeat the write, or use `position: "append"` or `"prepend"`, or `edit`, which are never refused. Peer writers are distinguished by identity. Anyone supplying an `agentId` or `x-ok-connection-id` must use a stable value unique to one writer, containing only ASCII `[A-Za-z0-9_-]` characters and 1–64 characters long. A nonconforming `agentId` is discarded: `POST /api/agent-write-md` and `POST /api/agent-write-batch` then treat the caller as unidentified, while `POST /api/lint/fix` falls back to the project [principal](./what-open-knowledge-writes.mdx) when available. A nonconforming `x-ok-connection-id` is silently replaced with a minted identity. A `POST /api/agent-write-md` caller sends its `agentId` on every write. The MCP write tools declare no `agentId` field. OpenKnowledge mints an identity per MCP connection unless an MCP Streamable HTTP client forwards a valid `x-ok-connection-id` while creating the protocol session. Writers that share or reuse an identity share [writer attribution](./core-concepts.md#attribution-and-collaboration), the server-side write session, and undo history, and are not refused against each other; the server does not detect identity collisions. Having an identity records you as a peer, so a `replace` carrying a different identity is refused for the next few seconds, while your own recent write does not arm the refusal against your follow-up `replace`. A writer that has no identity of its own is never recorded as a peer, so it never arms the refusal against a later writer. That covers a `POST /api/agent-write-md` that omits `agentId`, and a `lint` fix that both omits `agentId` and runs on a project with no principal. A caller that sent no `agentId` is still refused its own `replace` when a writer that did send one changed the document in the last few seconds, because that caller cannot be shown to be the recorded writer. Two `POST /api/agent-write-md` callers that both omit `agentId` are never refused against each other, though a recent change from a connected editor still refuses both of them.
+A write refused because the server is at its limit of concurrent agent write sessions returns `urn:ok:error:too-many-agent-sessions` (503): nothing was written, so it is safe to repeat. The problem body says so in `detail`, carries `committed: false`, and carries `retryAfterSeconds` alongside a matching `Retry-After` header. `POST /api/agent-write-md`, `POST /api/agent-patch`, `POST /api/frontmatter-patch` and `POST /api/lint/fix` answer this way, and the `write`, `edit` and `lint` fix tools append the detail and the bound to their error text (`Retry after 10s.`). `POST /api/agent-write-batch` keeps its `200` success envelope; each refused entry carries the problem type, `detail`, `committed: false` and `retryAfterSeconds` in its `error`, while sibling entries are unaffected. Wait that long and repeat the request. A `write` from a `template` creates the document before it patches the frontmatter, so when only that patch is refused the tool says so and the document already exists: apply the frontmatter with `edit` instead of repeating the `write`. For any other frontmatter failure on that path, re-read the document before changing it, because the patch may have been applied.
+
### Resolving a conflict
The MCP server has no conflict tools. An agent that hits `doc-in-conflict` or `stale-external-write` should name the file and ask the user to resolve it in the app; see [Resolving a conflict](../features/git/sync.mdx#resolving-a-conflict). HTTP integrations can list conflicts with `GET /api/sync/conflicts`, then read `GET /api/sync/conflict-content?file=<path>` for `base`, `ours`, `theirs`, the conflict kind, and its current `resolutionOptions`. To resolve one, send `POST /api/sync/resolve-conflict` with `{ file, strategy }`, choosing an offered strategy (`mine`, `theirs`, `content`, or `delete`). The `content` strategy also requires `content`; an empty string keeps an empty file. Content must be free of conflict markers. Use only the strategies returned for that conflict; its kind determines the commit behavior described above.
diff --git a/knip.config.ts b/knip.config.ts
index d3638888e..65f0e8807 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -147,15 +147,11 @@ 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'],
- ignoreDependencies: [
- 'yjs',
- ],
+ ignoreDependencies: ['yjs'],
},
'packages/desktop': {
entry: [
diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
index 4549c74b3..a50b00123 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -1,4 +1,3 @@
-
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
index 4fc2c11f9..6fcdc23f2 100644
--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -1,4 +1,3 @@
-
import { setTimeout as wait } from 'node:timers/promises';
import { normalizeBridge } from '@inkeep/open-knowledge-core';
import { updateYFragment } from '@tiptap/y-tiptap';
diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.ts
index 9f2f6feb6..40b5cdfd6 100644
--- a/packages/app/tests/integration/interior-edit-freshness.test.ts
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -1,4 +1,3 @@
-
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
index 2a085742b..93666af70 100644
--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -1,4 +1,3 @@
-
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.ts
index 878d5196b..867598d34 100644
--- a/packages/app/tests/integration/producer-guard-wiring.test.ts
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -1,4 +1,3 @@
-
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
index 4ada3cf26..0970ac12f 100644
--- a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
@@ -1,4 +1,3 @@
-
import { randomUUID } from 'node:crypto';
import { afterEach, describe, expect, test } from 'vitest';
import { agentWriteMd, createTestServer, type TestServer } from './test-harness';
diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
index cbe2b705f..b632185e1 100644
--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
@@ -1,4 +1,3 @@
-
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';
diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
index 89bc9b4d9..c530ce4ba 100644
--- a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
@@ -1,4 +1,3 @@
-
import { randomUUID } from 'node:crypto';
import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
import type * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.ts
index a78aeb0e4..d3767adc9 100644
--- a/packages/app/tests/integration/undo-after-rollback.test.ts
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -1,4 +1,3 @@
-
import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.ts
index e7cc69c3f..b076f955c 100644
--- a/packages/app/tests/integration/undo-recycle-reset.test.ts
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -1,4 +1,3 @@
-
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.ts
index 9ddcd0730..7935e35f8 100644
--- a/packages/app/tests/integration/undo-rederive-survival.test.ts
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -1,4 +1,3 @@
-
import { prependFrontmatter } from '@inkeep/open-knowledge-core';
import { Plugin, PluginKey } from '@tiptap/pm/state';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index 2a597ec3d..f4cc8a286 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,4 +1,3 @@
-
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 01ef76a9f..8fb428b90 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,4 +1,3 @@
-
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index fb0ba5a7c..fc267cbea 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index fa3cfcd86..bfd7e3109 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 8be632ba4..4d3250d3a 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,4 +1,3 @@
-
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index a8d0a8182..6ae57b0c8 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -91,7 +91,7 @@ KB docs are factual artifacts: every claim traceable, and **the source lives ins
- **No evidence?** Search and ingest the result, OR mark `(TODO: needs source)`, OR don't write the claim. Do NOT fabricate — unsourced speculation rots into untraceable tribal lore.
## Linking — standard markdown links (MUST)
-Link every noun-phrase that names another document — `[text](./relative/path.md)` — and link liberally. To point at one section of a long doc, in chat replies too, link `./path.md#heading-slug`. **Every link must resolve to a doc that exists by the time you're done** (a same-pass forward-reference you create later in the pass is fine; for one that genuinely won't exist, leave the mention as plain prose + a tracked task). Never backtick a link (`` `[text](./foo.md)` `` is a bug) and never use HTML `<a>`. **After every `write`/`edit`, read `brokenLinks`: fix reported `href`s; `[]` means all links resolve unless `brokenLinkSuppression` withheld reserved-log findings (not yours to repair) or a `link-check-deferred` warning says nothing was checked yet (that doc is re-checked only by a later write/edit of it or an `audit`, which may time out until startup finishes).** `audit` is authoritative; its same marker carries the same meaning. External web sources are NOT inline body links (see Grounding). Full rule set, slug rule + the `[[Page]]` legacy note: `references/linking.md`.
+Link every noun-phrase that names another document — `[text](./relative/path.md)` — and link liberally. To point at one section of a long doc, in chat replies too, link `./path.md#heading-slug`. **Every link must resolve to a doc that exists by the time you're done** (a same-pass forward-reference you create later in the pass is fine; for one that genuinely won't exist, leave the mention as plain prose + a tracked task). Never backtick a link (`` `[text](./foo.md)` `` is a bug) and never use HTML `<a>`. **After every `write`/`edit`, read `brokenLinks`: fix reported `href`s; `[]` means all links resolve unless `brokenLinkSuppression` withheld reserved-log findings (not yours to repair) or a `link-check-deferred` warning says nothing was checked yet (the server was still starting or busy with other writes; that doc is re-checked only by a later write/edit of it or an `audit`, which may time out while the server is still starting).** `audit` is authoritative; its same marker carries the same meaning. External web sources are NOT inline body links (see Grounding). Full rule set, slug rule + the `[[Page]]` legacy note: `references/linking.md`.
## Folders, frontmatter, templates
diff --git a/packages/server/assets/skills/project/references/linking.md b/packages/server/assets/skills/project/references/linking.md
index ee26f8a4a..a95ad644b 100644
--- a/packages/server/assets/skills/project/references/linking.md
+++ b/packages/server/assets/skills/project/references/linking.md
@@ -10,7 +10,7 @@
- **Every link must resolve to a doc that exists by the time you're done.** Within a single multi-doc authoring pass, linking a page you'll create later in the same pass is fine — `brokenLinks` reports it as `no-such-doc` until the target lands, an expected transient forward-reference rather than a wrong-path error. What's not acceptable is *leaving* a dead link behind: create the target in the same pass, or record it as a tracked task (`TaskCreate`, or your host's task tool — if the host has none, tell the user) and leave the mention as plain prose.
- **Never wrap a link in backticks.** `` `[text](./foo.md)` `` is a bug — the backticks make it render as literal code rather than a link.
- **Never use HTML anchors** (`<a href="...">`). Markdown link syntax only.
-- **`brokenLinks` on the write/edit response is your primary check — read it before walking away.** Every `write`/`edit` returns `brokenLinks` in the SAME payload: `[]` means every outbound link resolves only when `brokenLinkSuppression` is absent and `warnings` has no `link-check-deferred` entry (that entry means the server was still starting and checked nothing — that doc's links are re-checked only when you write or edit it again after startup, or by an `audit`, which can time out until then); a populated list names each broken `href` with its `resolvedTo` + `reason` (`no-such-doc` = resolved to a doc that doesn't exist; `no-such-file` = resolved to a linked asset / source file that isn't on disk at that path; `excluded` = the file is on disk but a `.gitignore` or `.okignore` rule keeps it out of the project, so re-include it or its folder with a `!` rule in `.okignore` (for example `!ignored/`) or link something else; `unresolvable` = the path escapes the content root, usually one `../` too many). This validates **every** local link, not just doc links: a wrong-depth `[src](../../foo.py)` to a source file is caught too. It is report-only — the write landed regardless; fix or remove every one in a follow-up `edit`.
+- **`brokenLinks` on the write/edit response is your primary check — read it before walking away.** Every `write`/`edit` returns `brokenLinks` in the SAME payload: `[]` means every outbound link resolves only when `brokenLinkSuppression` is absent and `warnings` has no `link-check-deferred` entry (that entry means the server was still starting, or busy with other writes, and checked nothing — that doc's links are re-checked only when you write or edit it again later, or by an `audit`, which can time out while the server is still starting); a populated list names each broken `href` with its `resolvedTo` + `reason` (`no-such-doc` = resolved to a doc that doesn't exist; `no-such-file` = resolved to a linked asset / source file that isn't on disk at that path; `excluded` = the file is on disk but a `.gitignore` or `.okignore` rule keeps it out of the project, so re-include it or its folder with a `!` rule in `.okignore` (for example `!ignored/`) or link something else; `unresolvable` = the path escapes the content root, usually one `../` too many). This validates **every** local link, not just doc links: a wrong-depth `[src](../../foo.py)` to a source file is caught too. It is report-only — the write landed regardless; fix or remove every one in a follow-up `edit`.
- **An empty `brokenLinks` alongside a `brokenLinkSuppression` does not mean every link resolves.** That field appears only when the project's reserved-log policy withheld findings, and it carries `{ reason: "reserved-log-policy", count: N }` and nothing else. No href comes back because none of them is repair work: the write landed in a lowercase-stemmed `log.md` or `log.mdx`, an append-only history whose entries deliberately reference pages that moved or were never written. **Never rewrite a reserved log's existing entries to clear a link.** Append new entries instead, and treat `links({ kind: "dead" })` on that file as a deliberate audit of raw state, never as a repair queue. The project can turn the policy off (**Settings ▸ This project ▸ Preferences ▸ Content rules**), in which case those findings come back through the normal channels.
- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Read `brokenLinkSuppression` on its result too: when present, the reserved-log policy withheld `count` findings, so a clean result is filtered rather than proof that every raw link resolves. Do not repair those log findings; use `links({ kind: "dead" })` only when deliberately inspecting raw state. Caveat: `audit` reports links only while the project's `validation.links` setting is not `off` (at `off` it returns clean with no warning), so if the project has silenced link validation, fall back to `links({ kind: "dead" })` — the unconditional read of the dead-link graph, which also lists skill-bundle docs excluded from the Problems plane (optionally scoped: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`). Otherwise `links` is the graph-navigation reader, supplemental to `audit`, not a substitute. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
- **The tool and the editor agree.** Both resolve a bare name the same way — exact, then slug, then folder index, then basename — so a link that opens when you click it is never reported dead, and a link reported dead is genuinely unresolvable. A target that names an asset, or names nothing at all, stays silent rather than being reported as a broken doc link.
diff --git a/packages/server/src/api-agent-session-capacity.test.ts b/packages/server/src/api-agent-session-capacity.test.ts
new file mode 100644
index 000000000..60bbcfa24
--- /dev/null
+++ b/packages/server/src/api-agent-session-capacity.test.ts
@@ -0,0 +1,119 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { Hocuspocus } from '@hocuspocus/server';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { AgentSessionManager } from './agent-sessions.ts';
+import { createApiExtension } from './api-extension.test-helper.ts';
+
+interface CapturedResponse {
+ status: number;
+ headers: Record<string, string>;
+ body: string;
+}
+
+async function post(
+ extension: ReturnType<typeof createApiExtension>,
+ url: string,
+ body: unknown,
+): Promise<CapturedResponse> {
+ const request = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
+ request.method = 'POST';
+ request.url = url;
+ request.headers = { host: 'localhost', 'content-type': 'application/json' };
+ const captured: CapturedResponse = { status: 0, headers: {}, body: '' };
+ const response = {
+ writeHead(status: number, headers?: Record<string, string>) {
+ captured.status = status;
+ for (const [key, value] of Object.entries(headers ?? {})) {
+ captured.headers[key.toLowerCase()] = value;
+ }
+ },
+ setHeader(key: string, value: string) {
+ captured.headers[key.toLowerCase()] = value;
+ },
+ end(text?: string) {
+ captured.body = text ?? '';
+ },
+ } as unknown as ServerResponse;
+ await (
+ extension as {
+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+ }
+ ).onRequest({ request, response });
+ return captured;
+}
+
+describe('agent writes refused at the session limit say nothing was committed (PRD-7398)', () => {
+ let contentDir: string;
+ let hocuspocus: Hocuspocus;
+ let sessionManager: AgentSessionManager;
+ let extension: ReturnType<typeof createApiExtension>;
+
+ beforeEach(async () => {
+ contentDir = mkdtempSync(join(tmpdir(), 'ok-session-capacity-'));
+ hocuspocus = new Hocuspocus({ quiet: true });
+ sessionManager = new AgentSessionManager(hocuspocus, {
+ maxSessions: 1,
+ minEvictableIdleMs: Number.POSITIVE_INFINITY,
+ });
+ await sessionManager.getSession('occupied', 'agent-occupant');
+ extension = createApiExtension({
+ hocuspocus,
+ sessionManager,
+ contentDir,
+ serverInstanceId: 'session-capacity-test',
+ getFileIndex: () => new Map(),
+ });
+ });
+
+ afterEach(async () => {
+ await sessionManager.closeAll();
+ rmSync(contentDir, { recursive: true, force: true });
+ });
+
+ test('agent-write answers 503 with Retry-After and committed: false', async () => {
+ const response = await post(extension, '/api/agent-write', {
+ docName: 'note',
+ content: '# Note\n',
+ });
+
+ expect(response.status).toBe(503);
+ expect(response.headers['retry-after']).toBe('10');
+ expect(JSON.parse(response.body)).toMatchObject({
+ status: 503,
+ type: 'urn:ok:error:too-many-agent-sessions',
+ committed: false,
+ retryAfterSeconds: 10,
+ });
+ expect(hocuspocus.documents.has('note')).toBe(false);
+ expect(existsSync(join(contentDir, 'note.md'))).toBe(false);
+ });
+
+ test('agent-write-batch marks each refused entry committed: false', async () => {
+ const response = await post(extension, '/api/agent-write-batch', {
+ docs: [{ docName: 'first', markdown: '# First\n' }],
+ });
+
+ expect(response.status).toBe(200);
+ expect(JSON.parse(response.body)).toMatchObject({
+ written: 0,
+ failed: 1,
+ results: [
+ {
+ status: 'error',
+ docName: 'first',
+ error: {
+ type: 'urn:ok:error:too-many-agent-sessions',
+ committed: false,
+ retryAfterSeconds: 10,
+ },
+ },
+ ],
+ });
+ expect(hocuspocus.documents.has('first')).toBe(false);
+ expect(existsSync(join(contentDir, 'first.md'))).toBe(false);
+ });
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 942a36628..321636edf 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -254,6 +254,13 @@ import {
} from './fs-traced.ts';
import { withParentLock } from './git-handle.ts';
import { isPathTrackedInGit } from './git-tracked-paths.ts';
+import {
+ AGENT_SESSION_CAPACITY_DETAIL,
+ AGENT_SESSION_CAPACITY_EXTENSIONS,
+ AGENT_SESSION_CAPACITY_TITLE,
+ AGENT_SESSION_CAPACITY_TYPE,
+ respondAgentSessionCapacity,
+} from './http/agent-session-capacity.ts';
import { type ApiRouteTable, createApiRequestPipeline } from './http/api-pipeline.ts';
import { createAssetRoutes } from './http/asset-routes.ts';
import { createCommentRoutes } from './http/comment-routes.ts';
@@ -306,6 +313,7 @@ import {
isPeerAdmitted,
} from './ingress-policy.ts';
import {
+ busyWriteLinkAdvisory,
deferredWriteLinkAdvisory,
type LinkAdvisoryPolicy,
type PrepareWriteLinkAdvisory,
@@ -373,6 +381,7 @@ import { readSkillInstallModeRaw } from './skill-placements.ts';
import type { SyncEngine } from './sync-engine.ts';
import { getMeter, withSpan, withSpanSync } from './telemetry.ts';
+import { createWriteAdvisoryGate } from './write-advisory-gate.ts';
import { computeWriteAdvisoryLinks, type WriteAdvisoryTargets } from './write-advisory-links.ts';
let _renameAttributionCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null =
@@ -1799,12 +1808,19 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
return readFrontmatterMetadataForDocName(docName);
}
+ const writeAdvisoryGate = createWriteAdvisoryGate();
+
async function computeOrphanHints(
docName: string,
): Promise<Array<{ type: 'orphan'; parentCandidates: string[]; message: string }> | undefined> {
if (!derivedDocumentIndex?.isReady()) return undefined;
try {
- const backlinks = await derivedDocumentIndex.getBacklinks(docName);
+ const backlinks = await writeAdvisoryGate.run(
+ 'orphan-hints',
+ () => derivedDocumentIndex.getBacklinks(docName),
+ () => undefined,
+ );
+ if (backlinks === undefined) return undefined;
if (backlinks.length > 0) return undefined;
const start = performance.now();
const candidates = findHubCandidates(docName, getFileIndex());
@@ -1938,7 +1954,14 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
const prepareWriteLinkAdvisory: PrepareWriteLinkAdvisory = async (writtenDocNames) => {
if (!isDerivedIndexReady()) return deferredWriteLinkAdvisory;
- const admitted = await collectAdmittedDocNames();
+ let admitted: Set<string> | null;
+ try {
+ admitted = await writeAdvisoryGate.run('link-check', collectAdmittedDocNames, () => null);
+ } catch (err) {
+ log.warn({ err }, '[link-check] write link advisory failed post-write; skipping link checks');
+ return busyWriteLinkAdvisory;
+ }
+ if (admitted === null) return busyWriteLinkAdvisory;
for (const docName of writtenDocNames) admitted.add(docName);
const targets: WriteAdvisoryTargets = {
fileExists: createLinkedFileExists(),
@@ -3634,13 +3657,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
return;
}
if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'agent-write', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
+ respondAgentSessionCapacity(res, e, 'agent-write');
return;
}
log.error({ err: e, requestId: getRequestId(_req) }, '[agent-write] handler failed');
@@ -3738,8 +3755,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
if (e instanceof AgentSessionCapacityError) {
return entryError(
docName,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
+ AGENT_SESSION_CAPACITY_TYPE,
+ AGENT_SESSION_CAPACITY_TITLE,
+ AGENT_SESSION_CAPACITY_DETAIL,
+ AGENT_SESSION_CAPACITY_EXTENSIONS,
);
}
log.error(
@@ -4834,23 +4853,29 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
linkPolicy.links !== 'off' &&
!isLinkIndexExcludedDoc(docName)
) {
- await recordDerivedLinkRewriteBestEffort(docName, source, 'lint-validation');
- const linksValidator = createProjectValidators({
- projectDir: projectDir ?? contentDir,
- contentDir,
- baseConfig: base,
- derivedDocumentIndex,
- linkPolicy,
- admittedDocNames: collectAdmittedDocNames,
- docFilePathFor: (d) => resolveDocFilePath(contentDir, d),
- localTargetInventory: linkedLocalTargetInventory,
- }).find((validator) => validator.id === 'links');
- if (linksValidator) {
- const run = await linksValidator.run({
- targetPath: resolveDocFilePath(contentDir, docName) ?? `${docName}.md`,
- });
- linkFindings = run.files.flatMap((file) => file.diagnostics);
- }
+ const index = derivedDocumentIndex;
+ linkFindings = await writeAdvisoryGate.run(
+ 'lint-links',
+ async () => {
+ await recordDerivedLinkRewriteBestEffort(docName, source, 'lint-validation');
+ const linksValidator = createProjectValidators({
+ projectDir: projectDir ?? contentDir,
+ contentDir,
+ baseConfig: base,
+ derivedDocumentIndex: index,
+ linkPolicy,
+ admittedDocNames: collectAdmittedDocNames,
+ docFilePathFor: (d) => resolveDocFilePath(contentDir, d),
+ localTargetInventory: linkedLocalTargetInventory,
+ }).find((validator) => validator.id === 'links');
+ if (!linksValidator) return [];
+ const run = await linksValidator.run({
+ targetPath: resolveDocFilePath(contentDir, docName) ?? `${docName}.md`,
+ });
+ return run.files.flatMap((file) => file.diagnostics);
+ },
+ () => [],
+ );
}
return [...lintFindings, ...linkFindings]
diff --git a/packages/server/src/api-write-advisory-deadline.test.ts b/packages/server/src/api-write-advisory-deadline.test.ts
new file mode 100644
index 000000000..bff16fece
--- /dev/null
+++ b/packages/server/src/api-write-advisory-deadline.test.ts
@@ -0,0 +1,216 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import simpleGit from 'simple-git';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import type { BacklinkEntry } from './backlink-index.ts';
+import { DerivedDocumentIndex } from './derived-document-index.ts';
+import { _resetDocExtensionsForTests } from './doc-extensions.ts';
+import { getLogger } from './logger.ts';
+import { createServer } from './server-factory.ts';
+import { WRITE_ADVISORY_DEADLINE_MS } from './write-advisory-gate.ts';
+
+interface ApiExtensionLike {
+ priority?: number;
+ onRequest?: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+}
+
+interface CapturedResponse {
+ status: number;
+ body: string;
+}
+
+const BUSY_LINK_CHECK = expect.objectContaining({
+ kind: 'link-check-deferred',
+ message: expect.stringContaining('busy with other writes'),
+});
+
+const RESPONSE_BOUND_MS = WRITE_ADVISORY_DEADLINE_MS + 5_000;
+
+const TEST_TIMEOUT_MS = 3 * RESPONSE_BOUND_MS;
+
+function settleWithin<T>(promise: Promise<T>, label: string, ms: number): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const deadline = new Promise<never>((_, reject) => {
+ timer = setTimeout(() => reject(new Error(`${label} did not settle within ${ms}ms`)), ms);
+ });
+ return Promise.race([promise, deadline]).finally(() => clearTimeout(timer));
+}
+
+async function post(
+ server: ReturnType<typeof createServer>,
+ url: string,
+ body: unknown,
+): Promise<CapturedResponse> {
+ const apiExt = server.hocuspocus.configuration.extensions.find(
+ (e): e is ApiExtensionLike =>
+ (e as ApiExtensionLike).priority === 100 &&
+ typeof (e as ApiExtensionLike).onRequest === 'function',
+ );
+ if (!apiExt?.onRequest) throw new Error('API extension (priority 100) not found on server');
+ const request = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
+ request.method = 'POST';
+ request.url = url;
+ request.headers = { host: 'localhost', 'content-type': 'application/json' };
+ const captured: CapturedResponse = { status: 0, body: '' };
+ const response = {
+ writeHead(status: number) {
+ captured.status = status;
+ },
+ setHeader() {},
+ end(text?: string) {
+ captured.body = text ?? '';
+ },
+ } as unknown as ServerResponse;
+ if (!(await server.nativeApi.dispatch(request, response))) {
+ await apiExt.onRequest({ request, response });
+ }
+ return captured;
+}
+
+describe('agent writes while the derived document index is not answering (PRD-7398)', {
+ timeout: TEST_TIMEOUT_MS,
+}, () => {
+ let tmpDir: string;
+ let server: ReturnType<typeof createServer>;
+ const releases: Array<() => void> = [];
+
+ function stallIndexQueries(): void {
+ let releaseBacklinks!: () => void;
+ const backlinks = new Promise<BacklinkEntry[]>((resolve) => {
+ releaseBacklinks = () => resolve([]);
+ });
+ let releaseDocNames!: () => void;
+ const docNames = new Promise<string[]>((resolve) => {
+ releaseDocNames = () => resolve([]);
+ });
+ releases.push(releaseBacklinks, releaseDocNames);
+ vi.spyOn(DerivedDocumentIndex.prototype, 'getBacklinks').mockReturnValue(backlinks);
+ vi.spyOn(DerivedDocumentIndex.prototype, 'getIndexedDocNames').mockReturnValue(docNames);
+ }
+
+ beforeEach(async () => {
+ _resetDocExtensionsForTests();
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-write-advisory-deadline-'));
+ const git = simpleGit({ baseDir: tmpDir });
+ await git.init();
+ await git.addConfig('user.name', 'Test User');
+ await git.addConfig('user.email', '[email protected]');
+ writeFileSync(join(tmpDir, 'index.md'), '# Index\n');
+ server = createServer({
+ contentDir: tmpDir,
+ projectDir: tmpDir,
+ quiet: true,
+ debounce: 100,
+ maxDebounce: 500,
+ gitEnabled: false,
+ });
+ await server.ready;
+ });
+
+ afterEach(async () => {
+ for (const release of releases.splice(0)) release();
+ vi.restoreAllMocks();
+ await server.destroy();
+ _resetDocExtensionsForTests();
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ test('a write answers once it is on disk and marks its link check as skipped', async () => {
+ const answered = await settleWithin(
+ post(server, '/api/agent-write-md', {
+ docName: 'answered',
+ markdown: '# Answered\n\nSee [[nowhere]].\n',
+ position: 'replace',
+ }),
+ 'agent-write-md before the stall',
+ RESPONSE_BOUND_MS,
+ );
+ expect(answered.status).toBe(200);
+ const answeredBody = JSON.parse(answered.body);
+ expect(answeredBody.brokenLinks).toEqual([
+ expect.objectContaining({ href: '[[nowhere]]', reason: 'no-such-doc' }),
+ ]);
+ expect(answeredBody.hints).toEqual([
+ expect.objectContaining({ type: 'orphan', parentCandidates: ['index'] }),
+ ]);
+
+ stallIndexQueries();
+ const filePath = join(tmpDir, 'stalled.md');
+
+ const write = await settleWithin(
+ post(server, '/api/agent-write-md', {
+ docName: 'stalled',
+ markdown: '# Stalled\n\nSee [[nowhere]].\n',
+ position: 'replace',
+ }),
+ 'agent-write-md during the stall',
+ RESPONSE_BOUND_MS,
+ );
+
+ expect(write.status).toBe(200);
+ expect(readFileSync(filePath, 'utf-8')).toBe('# Stalled\n\nSee [[nowhere]].\n');
+ const body = JSON.parse(write.body);
+ expect(body).toMatchObject({ brokenLinks: [], warnings: [BUSY_LINK_CHECK] });
+ expect(body.hints).toBeUndefined();
+ });
+
+ test('a write whose link index query fails answers as saved and marks its link check as skipped', async () => {
+ const warn = vi.spyOn(getLogger('api'), 'warn');
+ const failure = new Error('index query failed');
+ vi.spyOn(DerivedDocumentIndex.prototype, 'getIndexedDocNames').mockRejectedValue(failure);
+
+ const write = await post(server, '/api/agent-write-md', {
+ docName: 'failed-check',
+ markdown: '# Failed check\n\nSee [[nowhere]].\n',
+ position: 'replace',
+ });
+
+ expect(write.status).toBe(200);
+ expect(readFileSync(join(tmpDir, 'failed-check.md'), 'utf-8')).toBe(
+ '# Failed check\n\nSee [[nowhere]].\n',
+ );
+ expect(JSON.parse(write.body)).toMatchObject({ brokenLinks: [], warnings: [BUSY_LINK_CHECK] });
+
+ const batch = await post(server, '/api/agent-write-batch', {
+ docs: [{ docName: 'failed-batch', markdown: '# Failed batch\n\nSee [[nowhere]].\n' }],
+ });
+
+ expect(batch.status).toBe(200);
+ expect(readFileSync(join(tmpDir, 'failed-batch.md'), 'utf-8')).toBe(
+ '# Failed batch\n\nSee [[nowhere]].\n',
+ );
+ expect(JSON.parse(batch.body).results).toEqual([
+ expect.objectContaining({ status: 'written', brokenLinks: [], warnings: [BUSY_LINK_CHECK] }),
+ ]);
+ expect(warn).toHaveBeenCalledWith(
+ { err: failure },
+ '[link-check] write link advisory failed post-write; skipping link checks',
+ );
+ });
+
+ test('a batch write answers once its documents are on disk and marks link checks as skipped', async () => {
+ stallIndexQueries();
+
+ const batch = await settleWithin(
+ post(server, '/api/agent-write-batch', {
+ docs: [
+ { docName: 'batch-one', markdown: '# One\n\nSee [[nowhere]].\n' },
+ { docName: 'batch-two', markdown: '# Two\n' },
+ ],
+ }),
+ 'agent-write-batch during the stall',
+ RESPONSE_BOUND_MS,
+ );
+
+ expect(batch.status).toBe(200);
+ expect(readFileSync(join(tmpDir, 'batch-one.md'), 'utf-8')).toBe('# One\n\nSee [[nowhere]].\n');
+ expect(readFileSync(join(tmpDir, 'batch-two.md'), 'utf-8')).toBe('# Two\n');
+ expect(JSON.parse(batch.body).results).toEqual([
+ expect.objectContaining({ status: 'written', brokenLinks: [], warnings: [BUSY_LINK_CHECK] }),
+ expect.objectContaining({ status: 'written', brokenLinks: [], warnings: [BUSY_LINK_CHECK] }),
+ ]);
+ });
+});
diff --git a/packages/server/src/derived-document-index.test.ts b/packages/server/src/derived-document-index.test.ts
index d33b3459b..4f941621f 100644
--- a/packages/server/src/derived-document-index.test.ts
+++ b/packages/server/src/derived-document-index.test.ts
@@ -341,6 +341,27 @@ describe('DerivedDocumentIndex', () => {
expect(rig.signals).toEqual(['backlinks', 'graph']);
});
+ test('link rewrites debounce their backlink cache save instead of saving before returning', async () => {
+ vi.useFakeTimers();
+ const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
+ const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
+ const rig = createRig();
+ await settleStartup(rig);
+ backlinkSave.mockClear();
+ tagSave.mockClear();
+
+ await rig.index.recordLinkRewrite('source', 'See [[first]].\n');
+ await rig.index.recordLinkRewrite('source', 'See [[second]].\n');
+
+ expect(await rig.index.getBacklinks('second')).toHaveLength(1);
+ expect(backlinkSave).not.toHaveBeenCalled();
+
+ await vi.advanceTimersByTimeAsync(2000);
+
+ expect(backlinkSave).toHaveBeenCalledTimes(1);
+ expect(tagSave).not.toHaveBeenCalled();
+ });
+
test('direct rename moves link and tag membership atomically', async () => {
const rig = createRig();
await settleStartup(rig);
diff --git a/packages/server/src/derived-document-index.ts b/packages/server/src/derived-document-index.ts
index 2008f2625..a59cb1a83 100644
--- a/packages/server/src/derived-document-index.ts
+++ b/packages/server/src/derived-document-index.ts
@@ -499,7 +499,11 @@ export class DerivedDocumentIndex
}
recordLinkRewrite(documentName: string, markdown: string): Promise<void> {
- return this.recordDirectMutations([{ kind: 'link-rewrite', documentName, markdown }]);
+ return this.runCommand(async () => {
+ this.updateBacklinks(documentName, markdown);
+ this.scheduleSave(false);
+ this.signalBacklinks();
+ });
}
recordDirectMutations(mutations: readonly DerivedDocumentIndexMutation[]): Promise<void> {
diff --git a/packages/server/src/http/agent-session-capacity.ts b/packages/server/src/http/agent-session-capacity.ts
new file mode 100644
index 000000000..03046044d
--- /dev/null
+++ b/packages/server/src/http/agent-session-capacity.ts
@@ -0,0 +1,28 @@
+import type { ServerResponse } from 'node:http';
+import type { AgentSessionCapacityError } from '../agent-sessions.ts';
+import { errorResponse } from './error-response.ts';
+
+export const AGENT_SESSION_CAPACITY_TYPE = 'urn:ok:error:too-many-agent-sessions';
+export const AGENT_SESSION_CAPACITY_TITLE = 'Too many agent sessions.';
+export const AGENT_SESSION_CAPACITY_DETAIL =
+ 'The server is at its agent session limit, so this write was not applied and is safe to retry.';
+const AGENT_SESSION_CAPACITY_RETRY_AFTER_SECONDS = 10;
+
+export const AGENT_SESSION_CAPACITY_EXTENSIONS = {
+ committed: false,
+ retryAfterSeconds: AGENT_SESSION_CAPACITY_RETRY_AFTER_SECONDS,
+} as const;
+
+export function respondAgentSessionCapacity(
+ res: ServerResponse,
+ error: AgentSessionCapacityError,
+ handler: string,
+): void {
+ errorResponse(res, 503, AGENT_SESSION_CAPACITY_TYPE, AGENT_SESSION_CAPACITY_TITLE, {
+ handler,
+ cause: error,
+ detail: AGENT_SESSION_CAPACITY_DETAIL,
+ extensions: { ...AGENT_SESSION_CAPACITY_EXTENSIONS },
+ extraHeaders: { 'Retry-After': String(AGENT_SESSION_CAPACITY_RETRY_AFTER_SECONDS) },
+ });
+}
diff --git a/packages/server/src/http/agent-write-routes.test.ts b/packages/server/src/http/agent-write-routes.test.ts
index 472fc73d1..2941b4d79 100644
--- a/packages/server/src/http/agent-write-routes.test.ts
+++ b/packages/server/src/http/agent-write-routes.test.ts
@@ -106,28 +106,34 @@ describe('agent-write session capacity responses', () => {
['/api/agent-write-md', { docName: 'note', markdown: '# Note', position: 'replace' }],
['/api/frontmatter-patch', { docName: 'note', patch: { title: 'Note' } }],
['/api/agent-patch', { docName: 'note', find: 'old', replace: 'new' }],
- ])('%s returns the retryable problem when the session limit is full', async (path, body) => {
- const hocuspocus = new Hocuspocus({ quiet: true });
- const sessionManager = new AgentSessionManager(hocuspocus, {
- maxSessions: 1,
- minEvictableIdleMs: Number.POSITIVE_INFINITY,
- });
- try {
- await sessionManager.getSession('occupied', 'agent-occupant');
- const group = buildGroup({ hocuspocus, sessionManager });
- const route = group.table.resolve(path);
- if (!route?.dispatch) throw new Error(`${path} did not resolve to a dispatch handler`);
- const { res, captured } = makeCaptureRes();
- await route.dispatch(makeReq(path, body), res);
- expect(captured.status).toBe(503);
- expect(captured.headers['content-type']).toContain('application/problem+json');
- expect(captured.headers['retry-after']).toBe('10');
- expect(JSON.parse(captured.body)).toMatchObject({
- status: 503,
- type: 'urn:ok:error:too-many-agent-sessions',
+ ])(
+ '%s refuses before writing and says nothing was committed when the session limit is full',
+ async (path, body) => {
+ const hocuspocus = new Hocuspocus({ quiet: true });
+ const sessionManager = new AgentSessionManager(hocuspocus, {
+ maxSessions: 1,
+ minEvictableIdleMs: Number.POSITIVE_INFINITY,
});
- } finally {
- await sessionManager.closeAll();
- }
- });
+ try {
+ await sessionManager.getSession('occupied', 'agent-occupant');
+ const group = buildGroup({ hocuspocus, sessionManager });
+ const route = group.table.resolve(path);
+ if (!route?.dispatch) throw new Error(`${path} did not resolve to a dispatch handler`);
+ const { res, captured } = makeCaptureRes();
+ await route.dispatch(makeReq(path, body), res);
+ expect(captured.status).toBe(503);
+ expect(captured.headers['content-type']).toContain('application/problem+json');
+ expect(captured.headers['retry-after']).toBe('10');
+ expect(JSON.parse(captured.body)).toMatchObject({
+ status: 503,
+ type: 'urn:ok:error:too-many-agent-sessions',
+ committed: false,
+ retryAfterSeconds: 10,
+ });
+ expect(hocuspocus.documents.has('note')).toBe(false);
+ } finally {
+ await sessionManager.closeAll();
+ }
+ },
+ );
});
diff --git a/packages/server/src/http/agent-write-routes.ts b/packages/server/src/http/agent-write-routes.ts
index 90d39b8ea..8012a85b0 100644
--- a/packages/server/src/http/agent-write-routes.ts
+++ b/packages/server/src/http/agent-write-routes.ts
@@ -97,6 +97,7 @@ import {
type WriterIdentity,
} from '../shadow-repo.ts';
import { getMeter, withSpanSync } from '../telemetry.ts';
+import { respondAgentSessionCapacity } from './agent-session-capacity.ts';
import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import { getRequestId } from './request-id.ts';
@@ -509,13 +510,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup
return;
}
if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'agent-write-md', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
+ respondAgentSessionCapacity(res, e, 'agent-write-md');
return;
}
log.error({ err: e, requestId: getRequestId(_req) }, '[agent-write-md] handler failed');
@@ -756,13 +751,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup
});
} catch (e) {
if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'frontmatter-patch', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
+ respondAgentSessionCapacity(res, e, 'frontmatter-patch');
return;
}
log.error({ err: e, requestId: getRequestId(_req) }, '[frontmatter-patch] handler failed');
@@ -1093,13 +1082,7 @@ export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup
return;
}
if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'agent-patch', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
+ respondAgentSessionCapacity(res, e, 'agent-patch');
return;
}
log.error({ err: e, requestId: getRequestId(_req) }, '[agent-patch] handler failed');
diff --git a/packages/server/src/http/lint-write-routes.test.ts b/packages/server/src/http/lint-write-routes.test.ts
index d4b21ec0e..48fd48cfd 100644
--- a/packages/server/src/http/lint-write-routes.test.ts
+++ b/packages/server/src/http/lint-write-routes.test.ts
@@ -206,7 +206,10 @@ describe('createLintWriteRoutes lint-fix refusal responses', () => {
expect(JSON.parse(response.body)).toMatchObject({
status: 503,
type: 'urn:ok:error:too-many-agent-sessions',
+ committed: false,
+ retryAfterSeconds: 10,
});
+ expect(readFileSync(join(contentDir, 'note.md'), 'utf-8')).toBe('# Heading \n');
} finally {
await sessionManager.closeAll();
}
diff --git a/packages/server/src/http/lint-write-routes.ts b/packages/server/src/http/lint-write-routes.ts
index 4a9c01363..c759ade25 100644
--- a/packages/server/src/http/lint-write-routes.ts
+++ b/packages/server/src/http/lint-write-routes.ts
@@ -54,6 +54,7 @@ import {
resolveNativeConfigForDoc,
} from '../lint/resolve-config.ts';
import type { PinoLogger } from '../logger.ts';
+import { respondAgentSessionCapacity } from './agent-session-capacity.ts';
import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import { withValidation } from './request-validation.ts';
@@ -499,13 +500,7 @@ export function createLintWriteRoutes(deps: LintWriteRouteDeps): ApiRouteGroup {
return;
}
if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'lint-fix', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
+ respondAgentSessionCapacity(res, e, 'lint-fix');
return;
}
log.error({ err: e }, '[lint-fix] handler failed');
diff --git a/packages/server/src/link-advisory-policy.ts b/packages/server/src/link-advisory-policy.ts
index 4479ba11b..d6a41ba20 100644
--- a/packages/server/src/link-advisory-policy.ts
+++ b/packages/server/src/link-advisory-policy.ts
@@ -25,6 +25,12 @@ const LINK_CHECK_DEFERRED_WARNING: LinkCheckDeferredWarning = {
'Link checks were skipped because the link index is still building after server start, so an empty `brokenLinks` does not mean every link resolves. Links in this document are checked again only when it is written or edited after startup finishes, or by an `audit`, which waits for startup and can time out until then.',
};
+const LINK_CHECK_BUSY_WARNING: LinkCheckDeferredWarning = {
+ kind: 'link-check-deferred',
+ message:
+ 'Link checks were skipped because the link index did not answer, usually because it is busy with other writes, so an empty `brokenLinks` does not mean every link resolves. The write landed. Check this document later with `audit`, or read `brokenLinks` on your next write or edit of it.',
+};
+
export interface WriteLinkAdvisoryProjection {
brokenLinks: WriteAdvisoryLink[];
brokenLinkSuppression?: BrokenLinkSuppression;
@@ -49,6 +55,10 @@ export function deferredWriteLinkAdvisory(): WriteLinkAdvisory {
return { links: { brokenLinks: [] }, warnings: [LINK_CHECK_DEFERRED_WARNING] };
}
+export function busyWriteLinkAdvisory(): WriteLinkAdvisory {
+ return { links: { brokenLinks: [] }, warnings: [LINK_CHECK_BUSY_WARNING] };
+}
+
export function projectWriteAdvisoryLinks(
detected: WriteAdvisoryLink[],
sourceDocName: string,
diff --git a/packages/server/src/mcp/tools/advisory-warnings.test.ts b/packages/server/src/mcp/tools/advisory-warnings.test.ts
index 00c910546..d134df664 100644
--- a/packages/server/src/mcp/tools/advisory-warnings.test.ts
+++ b/packages/server/src/mcp/tools/advisory-warnings.test.ts
@@ -328,7 +328,7 @@ describe('deferred link check', () => {
test('formatAdvisoryBriefs emits one brief however many entries arrive', () => {
expect(formatAdvisoryBriefs([deferred, deferred])).toEqual([
- '⚠ Links not checked yet: the link index is still building (see warnings).',
+ '⚠ Links not checked yet: the link index is still building or busy (see warnings).',
]);
});
});
diff --git a/packages/server/src/mcp/tools/advisory-warnings.ts b/packages/server/src/mcp/tools/advisory-warnings.ts
index 415197953..1ddc3468a 100644
--- a/packages/server/src/mcp/tools/advisory-warnings.ts
+++ b/packages/server/src/mcp/tools/advisory-warnings.ts
@@ -120,7 +120,9 @@ export function formatAdvisoryBriefs(warnings: AdvisoryWarning[]): string[] {
if (render.length > 0) briefs.push(formatRenderWarningsBrief(render));
briefs.push(...lintEntries(warnings).map(formatLintBrief));
if (linkCheckDeferredEntries(warnings).length > 0) {
- briefs.push('⚠ Links not checked yet: the link index is still building (see warnings).');
+ briefs.push(
+ '⚠ Links not checked yet: the link index is still building or busy (see warnings).',
+ );
}
briefs.push(...unrecognizedEntries(warnings).map(formatUnrecognizedBrief));
return briefs;
diff --git a/packages/server/src/mcp/tools/edit.ts b/packages/server/src/mcp/tools/edit.ts
index a5432f606..300f5ae35 100644
--- a/packages/server/src/mcp/tools/edit.ts
+++ b/packages/server/src/mcp/tools/edit.ts
@@ -28,6 +28,7 @@ import {
agentIdentityFields,
CANONICAL_COMPONENT_GUIDANCE,
documentResultBaseShape,
+ errorTextWithDetail,
HOCUSPOCUS_NOT_RUNNING_ERROR,
httpPost,
httpPut,
@@ -185,14 +186,7 @@ async function handleDocBody(
...(args.summary !== undefined ? { summary: args.summary } : {}),
...agentIdentityFields(identity),
});
- if (!result.ok) {
- const detail =
- typeof result.detail === 'string' && result.detail.length > 0 ? result.detail : '';
- return textResult(
- detail ? `Error: ${result.error} (${detail})` : `Error: ${result.error}`,
- true,
- );
- }
+ if (!result.ok) return textResult(errorTextWithDetail(result), true);
return composeWritePreviewResult(
result,
normalized.docName,
@@ -222,16 +216,16 @@ async function handleDocFrontmatter(
...agentIdentityFields(identity),
});
if (!result.ok) {
- const errorText = result.error as string;
+ const errorText = errorTextWithDetail(result);
const fieldErrors =
result.fieldErrors && typeof result.fieldErrors === 'object'
? (result.fieldErrors as Record<string, string>)
: undefined;
if (fieldErrors) {
const lines = Object.entries(fieldErrors).map(([k, m]) => ` ${k}: ${m}`);
- return textResult(`Error: ${errorText}\n${lines.join('\n')}`, true);
+ return textResult(`${errorText}\n${lines.join('\n')}`, true);
}
- return textResult(`Error: ${errorText}`, true);
+ return textResult(errorText, true);
}
const setKeys: string[] = [];
const deleteKeys: string[] = [];
diff --git a/packages/server/src/mcp/tools/lint.ts b/packages/server/src/mcp/tools/lint.ts
index 01ae3f725..41f0ef80a 100644
--- a/packages/server/src/mcp/tools/lint.ts
+++ b/packages/server/src/mcp/tools/lint.ts
@@ -17,6 +17,7 @@ import {
capAuditWarnings,
countSummary,
degradationBlock,
+ errorTextWithDetail,
formatDiagnosticLine,
HOCUSPOCUS_NOT_RUNNING_ERROR,
httpGet,
@@ -224,7 +225,7 @@ async function fixLintDoc(
docName: normalized.docName,
...agentIdentityFields(identity),
});
- if (!result.ok) return textResult(`Error: ${String(result.error)}`, true);
+ if (!result.ok) return textResult(errorTextWithDetail(result), true);
const { ok: _ok, ...rest } = result;
const data = rest as LintFixPayload;
const file = data.file ?? normalized.docName;
diff --git a/packages/server/src/mcp/tools/session-capacity-refusal.test.ts b/packages/server/src/mcp/tools/session-capacity-refusal.test.ts
new file mode 100644
index 000000000..29789b64f
--- /dev/null
+++ b/packages/server/src/mcp/tools/session-capacity-refusal.test.ts
@@ -0,0 +1,217 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../../config/schema.ts';
+import {
+ AGENT_SESSION_CAPACITY_DETAIL,
+ AGENT_SESSION_CAPACITY_EXTENSIONS,
+ AGENT_SESSION_CAPACITY_TITLE,
+ AGENT_SESSION_CAPACITY_TYPE,
+} from '../../http/agent-session-capacity.ts';
+import { register as registerEdit } from './edit.ts';
+import { type FetchTestServer, startFetchTestServer } from './fetch-test-server.test-helper.ts';
+import { register as registerLint } from './lint.ts';
+import type { ServerInstance } from './shared.ts';
+import { register as registerWrite } from './write.ts';
+
+interface ToolResult {
+ content: Array<{ type: 'text'; text: string }>;
+ structuredContent?: Record<string, unknown>;
+ isError?: true;
+}
+type Handler = (args: Record<string, unknown>) => Promise<ToolResult>;
+
+const REFUSAL_TEXT = `${AGENT_SESSION_CAPACITY_TITLE} (${AGENT_SESSION_CAPACITY_DETAIL}) Retry after ${AGENT_SESSION_CAPACITY_EXTENSIONS.retryAfterSeconds}s.`;
+
+function capacityRefusal(): Response {
+ return Response.json(
+ {
+ type: AGENT_SESSION_CAPACITY_TYPE,
+ title: AGENT_SESSION_CAPACITY_TITLE,
+ status: 503,
+ instance: 'urn:uuid:11111111-2222-4333-8444-555555555555',
+ detail: AGENT_SESSION_CAPACITY_DETAIL,
+ ...AGENT_SESSION_CAPACITY_EXTENSIONS,
+ },
+ {
+ status: 503,
+ headers: { 'Retry-After': String(AGENT_SESSION_CAPACITY_EXTENSIONS.retryAfterSeconds) },
+ },
+ );
+}
+
+const STALE_TITLE = 'Edit retained; disk write blocked by a stale external-write conflict.';
+const STALE_DETAIL =
+ 'Your edit was applied and is retained in memory, but its Markdown disk write was skipped. Do not repeat this edit.';
+
+function staleExternalWrite(): Response {
+ return Response.json(
+ {
+ type: 'urn:ok:error:stale-external-write',
+ title: STALE_TITLE,
+ status: 409,
+ instance: 'urn:uuid:22222222-3333-4444-8555-666666666666',
+ detail: STALE_DETAIL,
+ },
+ { status: 409 },
+ );
+}
+
+const INVALID_TITLE = 'Frontmatter patch rejected: schema validation failed.';
+
+function invalidFrontmatterPatch(): Response {
+ return Response.json(
+ {
+ type: 'urn:ok:error:invalid-frontmatter-patch',
+ title: INVALID_TITLE,
+ status: 400,
+ instance: 'urn:uuid:33333333-4444-4555-8666-777777777777',
+ fieldErrors: { status: "'status' is not a recognized key" },
+ },
+ { status: 400 },
+ );
+}
+
+describe('MCP write paths relaying an agent-session capacity refusal', () => {
+ let testServer: FetchTestServer;
+ let cwd: string;
+ const handlers = new Map<string, Handler>();
+
+ beforeAll(async () => {
+ testServer = await startFetchTestServer({
+ hostname: '127.0.0.1',
+ async fetch(request) {
+ const { pathname } = new URL(request.url);
+ if (pathname === '/api/agent-write-md') {
+ const body = (await request.json()) as { docName?: string };
+ if (body.docName?.startsWith('notes/templated')) {
+ return Response.json({ ok: true, docName: body.docName });
+ }
+ return capacityRefusal();
+ }
+ if (pathname === '/api/frontmatter-patch') {
+ const body = (await request.json()) as { docName?: string };
+ if (body.docName === 'notes/templated-stale') return staleExternalWrite();
+ if (body.docName === 'notes/templated-invalid') return invalidFrontmatterPatch();
+ return capacityRefusal();
+ }
+ if (pathname === '/api/agent-patch' || pathname === '/api/lint/fix') {
+ return capacityRefusal();
+ }
+ return Response.json({ error: `unexpected route ${pathname}` }, { status: 500 });
+ },
+ });
+ cwd = mkdtempSync(join(tmpdir(), 'ok-session-capacity-refusal-'));
+ mkdirSync(join(cwd, '.ok'), { recursive: true });
+ mkdirSync(join(cwd, 'notes', '.ok', 'templates'), { recursive: true });
+ writeFileSync(
+ join(cwd, 'notes', '.ok', 'templates', 'note.md'),
+ '---\ntitle: Note\ndescription: A plain note\n---\n\n# Note\n',
+ );
+
+ const deps = {
+ serverUrl: `http://127.0.0.1:${testServer.port}`,
+ config: ConfigSchema.parse({}),
+ resolveCwd: async () => cwd,
+ };
+ for (const [name, register] of [
+ ['write', registerWrite],
+ ['edit', registerEdit],
+ ['lint', registerLint],
+ ] as const) {
+ const server = {
+ registerTool(_name: string, _cfg: unknown, toolHandler: Handler) {
+ handlers.set(name, toolHandler);
+ },
+ } as unknown as ServerInstance;
+ register(server, deps);
+ }
+ });
+
+ afterAll(() => {
+ testServer.stop();
+ rmSync(cwd, { recursive: true, force: true });
+ });
+
+ function tool(name: string): Handler {
+ const handler = handlers.get(name);
+ if (handler === undefined) throw new Error(`${name} tool did not register`);
+ return handler;
+ }
+
+ it('write shows the detail and retry interval', async () => {
+ const result = await tool('write')({
+ document: { path: 'notes/plain', content: '# Plain\n', position: 'replace' },
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(`Error: ${REFUSAL_TEXT}`);
+ });
+
+ it('write from a template says only its frontmatter was refused and how to apply it alone', async () => {
+ const result = await tool('write')({
+ document: { path: 'notes/templated', template: 'note', frontmatter: { status: 'draft' } },
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(
+ `Error: document created from template "note", but its frontmatter patch was refused, so the document exists without that frontmatter: ${REFUSAL_TEXT} Apply the frontmatter alone with edit({ document: { path: "notes/templated", frontmatter } }); do not repeat the templated write.`,
+ );
+ });
+
+ it('write from a template does not claim a frontmatter patch that failed after applying was refused', async () => {
+ const result = await tool('write')({
+ document: {
+ path: 'notes/templated-stale',
+ template: 'note',
+ frontmatter: { status: 'draft' },
+ },
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(
+ `Error: document created from template "note", but its frontmatter patch failed, and this response does not show whether the frontmatter was applied: ${STALE_TITLE} (${STALE_DETAIL}) Re-read the document before changing it; do not repeat the templated write.`,
+ );
+ });
+
+ it('write from a template treats a frontmatter validation rejection as nothing applied', async () => {
+ const result = await tool('write')({
+ document: {
+ path: 'notes/templated-invalid',
+ template: 'note',
+ frontmatter: { status: 'draft' },
+ },
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(
+ `Error: document created from template "note", but its frontmatter patch was refused, so the document exists without that frontmatter: ${INVALID_TITLE} Apply the frontmatter alone with edit({ document: { path: "notes/templated-invalid", frontmatter } }); do not repeat the templated write.`,
+ );
+ });
+
+ it('edit find/replace shows the detail and retry interval', async () => {
+ const result = await tool('edit')({
+ document: { path: 'notes/plain', find: 'Plain', replace: 'Changed' },
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(`Error: ${REFUSAL_TEXT}`);
+ });
+
+ it('edit frontmatter shows the detail and retry interval', async () => {
+ const result = await tool('edit')({
+ document: { path: 'notes/plain', frontmatter: { status: 'draft' } },
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(`Error: ${REFUSAL_TEXT}`);
+ });
+
+ it('lint fix shows the detail and retry interval', async () => {
+ const result = await tool('lint')({ document: 'notes/plain', fix: true });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0]?.text).toBe(`Error: ${REFUSAL_TEXT}`);
+ });
+});
diff --git a/packages/server/src/mcp/tools/shared.test.ts b/packages/server/src/mcp/tools/shared.test.ts
index ab062a2f3..8535a7b9f 100644
--- a/packages/server/src/mcp/tools/shared.test.ts
+++ b/packages/server/src/mcp/tools/shared.test.ts
@@ -16,6 +16,7 @@ import {
AUDIT_WARNING_CAP,
alignWarningCodes,
capAuditWarnings,
+ errorTextWithDetail,
HOCUSPOCUS_NOT_RUNNING_ERROR,
httpGet,
httpPost,
@@ -24,6 +25,7 @@ import {
okReservedPathRedirect,
outputSchemaWithText,
parseRenameCollidingPairs,
+ requestFailureText,
resolveProjectConfigContext,
resolveProjectServerContext,
TEXT_CHANNEL_FIELD,
@@ -64,6 +66,33 @@ describe('capAuditWarnings', () => {
const TEST_CONFIG: Config = ConfigSchema.parse({ content: { dir: 'content' } });
+describe('requestFailureText', () => {
+ test('renders the error, its detail and the retry bound', () => {
+ expect(
+ requestFailureText({
+ ok: false,
+ error: 'Too many agent sessions.',
+ detail: 'Nothing was applied.',
+ retryAfterSeconds: 10,
+ }),
+ ).toBe('Too many agent sessions. (Nothing was applied.) Retry after 10s.');
+ });
+
+ test('omits an empty or missing detail and a missing retry bound', () => {
+ expect(requestFailureText({ ok: false, error: 'Refused.', detail: '' })).toBe('Refused.');
+ expect(requestFailureText({ ok: false, error: 'Refused.' })).toBe('Refused.');
+ });
+
+ test('falls back when the error is not a string', () => {
+ expect(requestFailureText({ ok: false, detail: 'why' })).toBe('request failed (why)');
+ });
+
+ test('errorTextWithDetail prefixes the same text', () => {
+ const result = { ok: false, error: 'Refused.', detail: 'why', retryAfterSeconds: 3 };
+ expect(errorTextWithDetail(result)).toBe(`Error: ${requestFailureText(result)}`);
+ });
+});
+
describe('textResult', () => {
test('wraps text in MCP content array', () => {
const result = textResult('hello');
diff --git a/packages/server/src/mcp/tools/shared.ts b/packages/server/src/mcp/tools/shared.ts
index f7cc2a765..04a83b737 100644
--- a/packages/server/src/mcp/tools/shared.ts
+++ b/packages/server/src/mcp/tools/shared.ts
@@ -94,7 +94,7 @@ export const previewAttachWarningField = z
const brokenLinksOutputField = z
.array(BrokenLinkSchema)
.describe(
- 'Outbound internal links in the just-written doc that do not resolve. Always present — `[]` means every link resolves UNLESS `brokenLinkSuppression` is also present, in which case a project policy withheld findings, or `warnings` carries `link-check-deferred`, in which case the links were not checked because the server is still starting. A withholding that arrives in a shape this build cannot validate is dropped rather than relayed, so `brokenLinkSuppression` stays absent even though findings were withheld. The `audit` tool is the surface that discloses that case, through its `warnings`. Each: `{ href (as written), resolvedTo (the docName or content-root file path it pointed at, or null), reason: "no-such-doc" | "no-such-file" | "unresolvable" | "excluded" }`. `excluded` means the file exists on disk but a .gitignore or .okignore rule keeps it out of the project; a `!` rule in .okignore re-includes it or its folder. Report-only — the write landed regardless; fix in a follow-up edit.',
+ 'Outbound internal links in the just-written doc that do not resolve. Always present — `[]` means every link resolves UNLESS `brokenLinkSuppression` is also present, in which case a project policy withheld findings, or `warnings` carries `link-check-deferred`, in which case the links were not checked because the server is still starting or busy with other writes. A withholding that arrives in a shape this build cannot validate is dropped rather than relayed, so `brokenLinkSuppression` stays absent even though findings were withheld. The `audit` tool is the surface that discloses that case, through its `warnings`. Each: `{ href (as written), resolvedTo (the docName or content-root file path it pointed at, or null), reason: "no-such-doc" | "no-such-file" | "unresolvable" | "excluded" }`. `excluded` means the file exists on disk but a .gitignore or .okignore rule keeps it out of the project; a `!` rule in .okignore re-includes it or its folder. Report-only — the write landed regardless; fix in a follow-up edit.',
);
const brokenLinkSuppressionOutputField = BrokenLinkSuppressionSchema.optional().describe(
@@ -119,7 +119,7 @@ export const documentResultBaseShape = {
.min(1)
.optional()
.describe(
- "Advisory entries discriminated by `kind`. Write-integrity kinds — `content-divergence` (converged Y.Text didn't byte-match what you composed) and `disk-edit-reconciled` (an out-of-band disk edit was folded in before your write) — mean re-read the doc. The renderability kind `mermaid-parse-error` means the write landed but that fence will not render — fix it and re-edit. `link-check-deferred` means links were not checked because the server is still starting — that doc is re-checked only by a later write or edit of it, or an `audit`, which can time out until startup finishes.",
+ "Advisory entries discriminated by `kind`. Write-integrity kinds — `content-divergence` (converged Y.Text didn't byte-match what you composed) and `disk-edit-reconciled` (an out-of-band disk edit was folded in before your write) — mean re-read the doc. The renderability kind `mermaid-parse-error` means the write landed but that fence will not render — fix it and re-edit. `link-check-deferred` means links were not checked because the server is still starting or busy with other writes — that doc is re-checked only by a later write or edit of it, or an `audit`, which can time out until startup finishes.",
),
brokenLinks: brokenLinksOutputField,
brokenLinkSuppression: brokenLinkSuppressionOutputField,
@@ -147,10 +147,19 @@ export function nestDocResult(
return structured;
}
-export function errorTextWithDetail(result: { [key: string]: unknown }): string {
- const detail = typeof result.detail === 'string' ? ` (${result.detail})` : '';
+export function requestFailureText(result: { [key: string]: unknown }): string {
const title = typeof result.error === 'string' ? result.error : 'request failed';
- return `Error: ${title}${detail}`;
+ const detail =
+ typeof result.detail === 'string' && result.detail.length > 0 ? ` (${result.detail})` : '';
+ const retryAfter =
+ typeof result.retryAfterSeconds === 'number'
+ ? ` Retry after ${result.retryAfterSeconds}s.`
+ : '';
+ return `${title}${detail}${retryAfter}`;
+}
+
+export function errorTextWithDetail(result: { [key: string]: unknown }): string {
+ return `Error: ${requestFailureText(result)}`;
}
export function textResult(text: string, isError?: boolean) {
diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.ts
index 705725f78..60bebe8c7 100644
--- a/packages/server/src/mcp/tools/write.ts
+++ b/packages/server/src/mcp/tools/write.ts
@@ -6,6 +6,7 @@ import {
type FrontmatterPatch,
instantiateDoc,
normalizeBridge,
+ type ProblemType,
parseFrontmatterYaml,
SKILL_AUTHORING_WARNING_CODES,
serializeFrontmatterMap,
@@ -57,6 +58,7 @@ import {
previewUrlOutputField,
previewUrlSourceField,
ROUTED_CWD_DESCRIPTION,
+ requestFailureText,
resolveProjectServerContext,
serverRequestFailure,
summaryArgSchema,
@@ -186,6 +188,15 @@ export function composeWithFrontmatter(
return { ok: true, markdown: withFences(yamlBody) + cleanBody };
}
+const FRONTMATTER_PATCH_REJECTED_BEFORE_APPLY: ReadonlySet<unknown> = new Set<ProblemType>([
+ 'urn:ok:error:invalid-request',
+ 'urn:ok:error:invalid-frontmatter-patch',
+]);
+
+function frontmatterPatchAppliedNothing(result: { [key: string]: unknown }): boolean {
+ return result.committed === false || FRONTMATTER_PATCH_REJECTED_BEFORE_APPLY.has(result.type);
+}
+
async function writeOneDoc(
spec: DocSpec,
cwd: string,
@@ -310,21 +321,11 @@ async function writeOneDoc(
...agentIdentityFields(identity),
});
if (!result.ok) {
- const detail =
- typeof result.detail === 'string' && result.detail.length > 0 ? result.detail : '';
- const retryAfter =
- typeof result.retryAfterSeconds === 'number'
- ? ` Retry after ${result.retryAfterSeconds}s.`
- : '';
const recovery =
result.type === CONCURRENT_OVERWRITE_REFUSED_TYPE
? ' Wait and retry, or use edit for a targeted change.'
: '';
- return {
- docName,
- ok: false,
- error: `${detail ? `${String(result.error)} (${detail})` : String(result.error)}${retryAfter}${recovery}`,
- };
+ return { docName, ok: false, error: `${requestFailureText(result)}${recovery}` };
}
if (spec.template !== undefined && hasFrontmatter) {
@@ -337,7 +338,9 @@ async function writeOneDoc(
return {
docName,
ok: false,
- error: `document created from template but frontmatter failed: ${String(fmResult.error)}`,
+ error: frontmatterPatchAppliedNothing(fmResult)
+ ? `document created from template "${spec.template}", but its frontmatter patch was refused, so the document exists without that frontmatter: ${requestFailureText(fmResult)} Apply the frontmatter alone with edit({ document: { path: "${docName}", frontmatter } }); do not repeat the templated write.`
+ : `document created from template "${spec.template}", but its frontmatter patch failed, and this response does not show whether the frontmatter was applied: ${requestFailureText(fmResult)} Re-read the document before changing it; do not repeat the templated write.`,
};
}
}
@@ -999,7 +1002,7 @@ export function register(server: ServerInstance, deps: WriteDeps): void {
documents: looseObjectArray
.optional()
.describe(
- 'Batch write: per-doc result `{ docName, ok, position?, previewUrl?, warnings?, brokenLinks, brokenLinkSuppression?, error? }`. `brokenLinks` (possibly `[]`) is present on each successful entry, same as a single-doc write — and, same as a single-doc write, an empty list means every link resolves only on entries carrying no `brokenLinkSuppression` and no `link-check-deferred` warning (links not checked yet because the server is still starting).',
+ 'Batch write: per-doc result `{ docName, ok, position?, previewUrl?, warnings?, brokenLinks, brokenLinkSuppression?, error? }`. `brokenLinks` (possibly `[]`) is present on each successful entry, same as a single-doc write — and, same as a single-doc write, an empty list means every link resolves only on entries carrying no `brokenLinkSuppression` and no `link-check-deferred` warning (links not checked yet because the server is still starting or busy).',
),
previewUrl: previewUrlOutputField.optional(),
previewUrlSource: previewUrlSourceField,
diff --git a/packages/server/src/write-advisory-gate.test.ts b/packages/server/src/write-advisory-gate.test.ts
new file mode 100644
index 000000000..fe7edc13b
--- /dev/null
+++ b/packages/server/src/write-advisory-gate.test.ts
@@ -0,0 +1,343 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { getLogger } from './logger.ts';
+import {
+ createWriteAdvisoryGate,
+ WRITE_ADVISORY_GATE_CLOSED_LOG,
+ WRITE_ADVISORY_GATE_LOG_INTERVAL_MS,
+ WRITE_ADVISORY_GATE_REOPENED_LOG,
+ type WriteAdvisoryGate,
+} from './write-advisory-gate.ts';
+
+const LATE_FAILURE_MESSAGE = '[write-advisory] deferred advisory failed after its deadline';
+
+function warnMessages(warn: { mock: { calls: unknown[][] } }): unknown[] {
+ return warn.mock.calls.map((call) => call[1]);
+}
+
+function captureGateLines(): () => Array<[string, unknown]> {
+ const lines: Array<[string, unknown]> = [];
+ const logger = getLogger('write-advisory');
+ const capture = (data: unknown, message: string): void => {
+ if (
+ message === WRITE_ADVISORY_GATE_CLOSED_LOG ||
+ message === WRITE_ADVISORY_GATE_REOPENED_LOG
+ ) {
+ lines.push([message, data]);
+ }
+ };
+ vi.spyOn(logger, 'warn').mockImplementation(capture);
+ vi.spyOn(logger, 'info').mockImplementation(capture);
+ return () => [...lines];
+}
+
+function stalled<T>(): {
+ promise: Promise<T>;
+ resolve: (value: T) => void;
+ reject: (error: Error) => void;
+} {
+ let resolve!: (value: T) => void;
+ let reject!: (error: Error) => void;
+ const promise = new Promise<T>((onResolve, onReject) => {
+ resolve = onResolve;
+ reject = onReject;
+ });
+ return { promise, resolve, reject };
+}
+
+describe('write advisory gate', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+ });
+
+ test('returns the advisory when it answers before the deadline', async () => {
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+
+ const result = gate.run(
+ 'link-check',
+ async () => ['checked'],
+ () => ['fallback'],
+ );
+
+ await expect(result).resolves.toEqual(['checked']);
+ });
+
+ test('answers with the fallback at the deadline while the advisory is still waiting', async () => {
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const slow = stalled<string>();
+ let settled: string | undefined;
+
+ void gate
+ .run(
+ 'orphan-hints',
+ () => slow.promise,
+ () => 'deferred',
+ )
+ .then((value) => {
+ settled = value;
+ });
+ await vi.advanceTimersByTimeAsync(999);
+ expect(settled).toBeUndefined();
+ await vi.advanceTimersByTimeAsync(1);
+
+ expect(settled).toBe('deferred');
+ slow.resolve('late');
+ });
+
+ test('propagates an advisory failure that arrives before the deadline', async () => {
+ const warn = vi.spyOn(getLogger('write-advisory'), 'warn');
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+
+ const result = gate.run(
+ 'link-check',
+ async () => {
+ throw new Error('index closed');
+ },
+ () => 'fallback',
+ );
+
+ await expect(result).rejects.toThrow('index closed');
+ await vi.advanceTimersByTimeAsync(0);
+ expect(warnMessages(warn)).not.toContain(LATE_FAILURE_MESSAGE);
+ });
+
+ test('logs an advisory failure that arrives after the deadline with its kind and error', async () => {
+ const warn = vi.spyOn(getLogger('write-advisory'), 'warn');
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const failing = stalled<string>();
+ const first = gate.run(
+ 'lint-links',
+ () => failing.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(first).resolves.toBe('deferred');
+ const failure = new Error('index closed late');
+
+ failing.reject(failure);
+ await vi.advanceTimersByTimeAsync(0);
+
+ expect(warn).toHaveBeenCalledWith(
+ { err: failure, advisory: 'lint-links' },
+ LATE_FAILURE_MESSAGE,
+ );
+ });
+
+ async function closeFor(gate: WriteAdvisoryGate, closedMs: number): Promise<void> {
+ const slow = stalled<string>();
+ const deferred = gate.run(
+ 'orphan-hints',
+ () => slow.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(deferred).resolves.toBe('deferred');
+ await vi.advanceTimersByTimeAsync(closedMs);
+ slow.resolve('late');
+ await vi.advanceTimersByTimeAsync(0);
+ }
+
+ test('logs the gate reopening with how long it was closed and how many advisories it skipped', async () => {
+ const gateLines = captureGateLines();
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const slow = stalled<string>();
+ const first = gate.run(
+ 'link-check',
+ () => slow.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(first).resolves.toBe('deferred');
+ const closedLine: [string, unknown] = [
+ WRITE_ADVISORY_GATE_CLOSED_LOG,
+ { advisory: 'link-check', deadlineMs: 1_000, closings: 1, busySkipped: 0, closedMs: 0 },
+ ];
+ expect(gateLines()).toEqual([closedLine]);
+
+ await gate.run(
+ 'lint-links',
+ async () => 'checked',
+ () => 'busy',
+ );
+ await gate.run(
+ 'orphan-hints',
+ async () => 'checked',
+ () => 'busy',
+ );
+ await vi.advanceTimersByTimeAsync(4_000);
+ slow.resolve('late');
+ await vi.advanceTimersByTimeAsync(0);
+ expect(gateLines()).toEqual([closedLine]);
+
+ await vi.advanceTimersByTimeAsync(WRITE_ADVISORY_GATE_LOG_INTERVAL_MS);
+
+ expect(gateLines()).toEqual([
+ closedLine,
+ [WRITE_ADVISORY_GATE_REOPENED_LOG, { closings: 0, busySkipped: 2, closedMs: 4_000 }],
+ ]);
+ });
+
+ test('a gate that never reopens logs its closing once and no reopening', async () => {
+ const gateLines = captureGateLines();
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const stuck = stalled<string>();
+ const first = gate.run(
+ 'orphan-hints',
+ () => stuck.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(first).resolves.toBe('deferred');
+
+ for (let index = 0; index < 5; index++) {
+ await gate.run(
+ 'link-check',
+ async () => 'checked',
+ () => 'busy',
+ );
+ }
+ await vi.advanceTimersByTimeAsync(3 * WRITE_ADVISORY_GATE_LOG_INTERVAL_MS);
+
+ expect(gateLines()).toEqual([
+ [
+ WRITE_ADVISORY_GATE_CLOSED_LOG,
+ { advisory: 'orphan-hints', deadlineMs: 1_000, closings: 1, busySkipped: 0, closedMs: 0 },
+ ],
+ ]);
+ stuck.resolve('late');
+ });
+
+ test('closings inside one log interval are carried by the line that ends it', async () => {
+ const gateLines = captureGateLines();
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+
+ await closeFor(gate, 2_000);
+ await closeFor(gate, 3_000);
+ await closeFor(gate, 500);
+ expect(gateLines()).toHaveLength(1);
+
+ await vi.advanceTimersByTimeAsync(WRITE_ADVISORY_GATE_LOG_INTERVAL_MS);
+ await vi.advanceTimersByTimeAsync(2 * WRITE_ADVISORY_GATE_LOG_INTERVAL_MS);
+
+ expect(gateLines()).toEqual([
+ [
+ WRITE_ADVISORY_GATE_CLOSED_LOG,
+ { advisory: 'orphan-hints', deadlineMs: 1_000, closings: 1, busySkipped: 0, closedMs: 0 },
+ ],
+ [WRITE_ADVISORY_GATE_REOPENED_LOG, { closings: 2, busySkipped: 0, closedMs: 5_500 }],
+ ]);
+ });
+
+ test('a reopening after a quiet log interval is logged at once', async () => {
+ const gateLines = captureGateLines();
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+
+ await closeFor(gate, WRITE_ADVISORY_GATE_LOG_INTERVAL_MS);
+
+ expect(gateLines()).toEqual([
+ [
+ WRITE_ADVISORY_GATE_CLOSED_LOG,
+ { advisory: 'orphan-hints', deadlineMs: 1_000, closings: 1, busySkipped: 0, closedMs: 0 },
+ ],
+ [
+ WRITE_ADVISORY_GATE_REOPENED_LOG,
+ { closings: 0, busySkipped: 0, closedMs: WRITE_ADVISORY_GATE_LOG_INTERVAL_MS },
+ ],
+ ]);
+ });
+
+ test('skips new advisories without starting them while an earlier one is overdue, then resumes', async () => {
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const slow = stalled<string>();
+ const first = gate.run(
+ 'link-check',
+ () => slow.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(first).resolves.toBe('deferred');
+ const work = vi.fn(async () => 'checked');
+
+ await expect(gate.run('lint-links', work, () => 'busy')).resolves.toBe('busy');
+ expect(work).not.toHaveBeenCalled();
+
+ slow.resolve('late');
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(gate.run('lint-links', work, () => 'busy')).resolves.toBe('checked');
+ expect(work).toHaveBeenCalledTimes(1);
+ });
+
+ test('stays closed until every overdue advisory has settled', async () => {
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const first = stalled<string>();
+ const second = stalled<string>();
+ const firstRun = gate.run(
+ 'link-check',
+ () => first.promise,
+ () => 'deferred',
+ );
+ const secondRun = gate.run(
+ 'orphan-hints',
+ () => second.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(firstRun).resolves.toBe('deferred');
+ await expect(secondRun).resolves.toBe('deferred');
+ const work = vi.fn(async () => 'checked');
+
+ first.resolve('late');
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(gate.run('lint-links', work, () => 'busy')).resolves.toBe('busy');
+ expect(work).not.toHaveBeenCalled();
+
+ second.resolve('late');
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(gate.run('lint-links', work, () => 'busy')).resolves.toBe('checked');
+ expect(work).toHaveBeenCalledTimes(1);
+ });
+
+ test('an overdue advisory that later fails also reopens the gate', async () => {
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+ const failing = stalled<string>();
+ const first = gate.run(
+ 'link-check',
+ () => failing.promise,
+ () => 'deferred',
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+ await expect(first).resolves.toBe('deferred');
+
+ failing.reject(new Error('late failure'));
+ await vi.advanceTimersByTimeAsync(0);
+
+ await expect(
+ gate.run(
+ 'link-check',
+ async () => 'checked',
+ () => 'busy',
+ ),
+ ).resolves.toBe('checked');
+ });
+
+ test('advisories that answer in time never close the gate', async () => {
+ const gate = createWriteAdvisoryGate({ deadlineMs: 1_000 });
+
+ for (let index = 0; index < 5; index++) {
+ await expect(
+ gate.run(
+ 'orphan-hints',
+ async () => index,
+ () => -1,
+ ),
+ ).resolves.toBe(index);
+ }
+ });
+});
diff --git a/packages/server/src/write-advisory-gate.ts b/packages/server/src/write-advisory-gate.ts
new file mode 100644
index 000000000..1301e9adc
--- /dev/null
+++ b/packages/server/src/write-advisory-gate.ts
@@ -0,0 +1,149 @@
+import type { Counter } from '@opentelemetry/api';
+import { getLogger } from './logger.ts';
+import { getMeter } from './telemetry.ts';
+
+const log = getLogger('write-advisory');
+
+type WriteAdvisoryKind = 'orphan-hints' | 'link-check' | 'lint-links';
+
+type WriteAdvisoryDeferralReason = 'deadline' | 'busy';
+
+export interface WriteAdvisoryGate {
+ run<T>(advisory: WriteAdvisoryKind, work: () => Promise<T>, fallback: () => T): Promise<T>;
+}
+
+export const WRITE_ADVISORY_DEADLINE_MS = 1_500;
+
+export const WRITE_ADVISORY_GATE_LOG_INTERVAL_MS = 60_000;
+
+export const WRITE_ADVISORY_GATE_CLOSED_LOG =
+ '[write-advisory] document index did not answer within the write-advisory deadline; skipping index-backed write advisories until it catches up';
+
+export const WRITE_ADVISORY_GATE_REOPENED_LOG =
+ '[write-advisory] document index caught up; index-backed write advisories resumed';
+
+let _deferredCounter: Counter | null = null;
+function deferredCounter(): Counter {
+ _deferredCounter ||= getMeter().createCounter('ok.write_advisory.deferred', {
+ description:
+ 'Post-write advisories that depend on the derived document index and were omitted from a write response: reason=deadline when the index did not answer within the write-advisory deadline, reason=busy when an earlier advisory was still waiting past its deadline so this one was not started. The write itself was durable either way.',
+ unit: '{advisory}',
+ });
+ return _deferredCounter;
+}
+
+const DEADLINE_PASSED = Symbol('write-advisory-deadline');
+
+export function createWriteAdvisoryGate(options: { deadlineMs?: number } = {}): WriteAdvisoryGate {
+ const deadlineMs = options.deadlineMs ?? WRITE_ADVISORY_DEADLINE_MS;
+ let overdue = 0;
+ let closedSince = 0;
+ let closingAdvisory: WriteAdvisoryKind | undefined;
+ let closings = 0;
+ let busySkipped = 0;
+ let closedMs = 0;
+ let lastLineAt: number | undefined;
+ let pendingLine: ReturnType<typeof setTimeout> | undefined;
+
+ const logGateState = (): void => {
+ const now = Date.now();
+ lastLineAt = now;
+ const closed = overdue > 0;
+ const counts = {
+ closings,
+ busySkipped,
+ closedMs: closed ? closedMs + now - closedSince : closedMs,
+ };
+ closings = 0;
+ busySkipped = 0;
+ closedMs = 0;
+ closedSince = now;
+ if (closed) {
+ log.warn(
+ { advisory: closingAdvisory, deadlineMs, ...counts },
+ WRITE_ADVISORY_GATE_CLOSED_LOG,
+ );
+ } else {
+ log.info(counts, WRITE_ADVISORY_GATE_REOPENED_LOG);
+ }
+ };
+
+ const noteGateChange = (): void => {
+ if (pendingLine !== undefined) return;
+ const now = Date.now();
+ const nextLineAt =
+ lastLineAt === undefined ? now : lastLineAt + WRITE_ADVISORY_GATE_LOG_INTERVAL_MS;
+ if (now >= nextLineAt) {
+ logGateState();
+ return;
+ }
+ pendingLine = setTimeout(() => {
+ pendingLine = undefined;
+ logGateState();
+ }, nextLineAt - now);
+ pendingLine.unref();
+ };
+
+ const close = (advisory: WriteAdvisoryKind): void => {
+ overdue += 1;
+ if (overdue > 1) return;
+ closedSince = Date.now();
+ closingAdvisory = advisory;
+ closings += 1;
+ noteGateChange();
+ };
+
+ const release = (): void => {
+ overdue -= 1;
+ if (overdue > 0) return;
+ closedMs += Date.now() - closedSince;
+ noteGateChange();
+ };
+
+ const defer = <T>(
+ advisory: WriteAdvisoryKind,
+ reason: WriteAdvisoryDeferralReason,
+ fallback: () => T,
+ ): T => {
+ deferredCounter().add(1, { advisory, reason });
+ return fallback();
+ };
+
+ return {
+ async run(advisory, work, fallback) {
+ if (overdue > 0) {
+ busySkipped += 1;
+ return defer(advisory, 'busy', fallback);
+ }
+ let settledWork = false;
+ let counted = false;
+ const pending = Promise.resolve().then(work);
+ const settle = (): void => {
+ settledWork = true;
+ if (counted) release();
+ };
+ void pending.then(settle, settle);
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const deadline = new Promise<typeof DEADLINE_PASSED>((resolve) => {
+ timer = setTimeout(() => resolve(DEADLINE_PASSED), deadlineMs);
+ });
+ try {
+ const settled = await Promise.race([pending, deadline]);
+ if (settled !== DEADLINE_PASSED) return settled;
+ if (!settledWork) {
+ counted = true;
+ close(advisory);
+ }
+ void pending.catch((err: unknown) => {
+ log.warn(
+ { err, advisory },
+ '[write-advisory] deferred advisory failed after its deadline',
+ );
+ });
+ return defer(advisory, 'deadline', fallback);
+ } finally {
+ clearTimeout(timer);
+ }
+ },
+ };
+}