Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
PRD-9771 Keep the edited side of engine-less files, config and skills (#7203)
mike-inkeep2c0e8469b25d
diff --git a/.changeset/engineless-files-keep-edits.md b/.changeset/engineless-files-keep-edits.mdnew file mode 100644index 000000000..8945691e9--- /dev/null+++ b/.changeset/engineless-files-keep-edits.md@@ -0,0 +1,5 @@+---+'@inkeep/open-knowledge': patch+---++Unsaved edits to Mermaid, Excalidraw, text and settings files and to global and external skills are no longer lost to an outside change: the version set aside goes to history, or to a backup folder when history is unavailable, with a notice saying where.diff --git a/docs/content/features/timeline-and-recovery.mdx b/docs/content/features/timeline-and-recovery.mdxindex a424bdd0d..eb1716221 100644--- a/docs/content/features/timeline-and-recovery.mdx+++ b/docs/content/features/timeline-and-recovery.mdx@@ -19,11 +19,13 @@ Timeline entries include:- **File system** changes made outside of OpenKnowledge- **Recovered content** entries OpenKnowledge saves itself. They hold a version it could not merge into the document, such as the pre-change version when an external file change arrives with no acknowledged base.- **Before an outside change was merged** entries, two per collision, when an outside edit and yours change the same paragraph: one holds your version (**Version in OpenKnowledge**), the other the outside version (**Outside version**), as they were before both were kept.-- **Not merged** entries when an outside edit cannot be merged safely. The entry holds the version that was set aside, labelled **Outside version** or **Version in OpenKnowledge**.+- **Not merged** entries when an outside edit cannot be merged safely, or changed a Mermaid, Excalidraw or plain-text file, which OpenKnowledge cannot merge. The entry holds the version that was set aside, labelled **Outside version** or **Version in OpenKnowledge**.Project-wide checkpoints saved by agents via the [`checkpoint` MCP tool](/docs/reference/mcp#tools) do not appear on the timeline; agents find and restore them with the `history` and `restore_version` tools.-OpenKnowledge also saves recovery entries itself. When it detects an external file change on its own and has no acknowledged base to merge the change against, the disk version replaces the document and the pre-change version is preserved as a **Recovered content** entry, which you can restore like any other timeline entry. When an outside edit and the document's open version change the same paragraph, both versions stay in the document, the open version first and the outside version directly under it, nothing is asked, and both earlier versions are saved as entries. When one side deleted a paragraph the other changed, the changed version stays in the document, and both earlier versions are saved as entries. When the two cannot be merged safely, for example a very large file or a merge OpenKnowledge cannot verify, the open version stays and the outside version is saved as an entry. An agent write that meets an outside edit follows the same rules and lands. OpenKnowledge raises a conflict, and changes nothing until it is resolved, when the file on disk holds Git conflict markers, when it cannot save the outside version to the timeline, when an agent write has no acknowledged version to merge against, or when another app restores an exact older copy over an acknowledged edit (see [Conflicts that don't come from Git](/docs/features/git/sync#conflicts-that-dont-come-from-git)).+OpenKnowledge also saves recovery entries itself. When it detects an external file change on its own and has no acknowledged base to merge the change against, the disk version replaces the document and the pre-change version is preserved as a **Recovered content** entry, which you can restore like any other timeline entry. When an outside edit and the document's open version change the same paragraph, both versions stay in the document, the open version first and the outside version directly under it, nothing is asked, and both earlier versions are saved as entries. When one side deleted a paragraph the other changed, the changed version stays in the document, and both earlier versions are saved as entries. When the two cannot be merged safely, for example a very large file or a merge OpenKnowledge cannot verify, the open version stays and the outside version is saved as an entry. An agent write that meets an outside edit follows the same rules and lands. A Mermaid, Excalidraw or plain-text file that changed outside while you had unsaved edits keeps your version, on screen and on disk, and the outside version is saved as a **Not merged** entry; with no unsaved edits, the outside version simply replaces what is shown. Global skills and skills opened from outside the project merge outside changes the same way documents do, and their entries are saved in the history of the project that was open at the time. When your settings files change outside OpenKnowledge, a valid change applies and any setting you were still changing is saved to the project's history. A change that is not valid settings is not applied: Settings reports it, and at your next settings save it is saved to the project's history and replaced by your settings. A notice at the top of Settings says which happened. The app cannot show settings history yet; agents can read it with the `history` tool. OpenKnowledge raises a conflict, and changes nothing until it is resolved, when the file on disk holds Git conflict markers, when it cannot save the outside version to the timeline, when an agent write has no acknowledged version to merge against, or when another app restores an exact older copy over an acknowledged edit (see [Conflicts that don't come from Git](/docs/features/git/sync#conflicts-that-dont-come-from-git)).++When the project has no history to save to, for example with no shadow repo, the version set aside for a Mermaid, Excalidraw or plain-text file, a skill or a settings file is saved instead under `~/.ok/edit-backups/discarded/`, and the notice names the file. A project's file gets a folder inside a folder for that project; a global or external skill gets one folder that every project shares. Each folder keeps its five newest copies. If neither can take the version, or the file keeps changing, cannot be read, or changed to text that is not UTF-8, nothing is saved yet: your edits stay on screen and in the recovery copy, and OpenKnowledge tries again, for a file that is not UTF-8 once it changes. A separate notice says why, beside any notice that a version was kept. It goes away once the save lands, or after a restart that leaves nothing held, and if you dismiss it while the save is still held, it comes back at the next try that fails. For a settings file there is no such notice: Settings says why each time the cause changes.When another app or a terminal renames or moves the file of an open document, the document stays open under its new name with any typing you have not saved yet, and its timeline and its notice move with it.diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdxindex 7a9a06b9f..dd38fa06d 100644--- a/docs/content/reference/mcp.mdx+++ b/docs/content/reference/mcp.mdx@@ -118,7 +118,9 @@ A doc can land in conflict through a Git merge, a pull that collides with a locaA write that first detects the stale file during its final disk flush returns a different 409, `urn:ok:error:stale-external-write`. The edit reached collaborative state and the recovery snapshot, but the disk write did not happen. Ask the user to resolve the conflict, then re-read the document. Do not repeat the operation: compare the resolved content with the intended result and make only any remaining edit.-When OpenKnowledge saves a Markdown document, it first compares the file with the version it last agreed with the disk. If another tool changed the file, that change is merged into the document before the save, so the write succeeds and the file holds both edits; re-read the document before editing it further. This covers saves of edits made in the app, idle saves, the save at quit, the in-app agent's whole-document write and the agent write routes. Other writers, such as rename, delete, templates, skills, and Mermaid, Excalidraw and plain-text documents, do not run this comparison yet. The stale-external-write case above is the exception: when the file holds a version that an earlier agent write replaced, the write returns that 409 instead. If the save cannot finish safely, the write returns `urn:ok:error:save-held` (503). The body carries `reason` (what holds the save), `retryWhen` (what the server's own save waits for; it is never a cue to repeat the request) and `nextStep: re-read`; in a batch response the same fields appear on that entry's `error`. When the file cannot be read (`pending-unreadable`, with the errno in `causeCode`), keeps changing (`pending-exhausted`, `pending-base-moved`) or the outside change could not be merged (`pending-intake-failed`), the next edit or the idle save within a few minutes saves it (`retryWhen: next-save`). When OpenKnowledge has no agreed version of the file to merge with (`pending-intake-failed-no-base`, or any hold on such a document), the edit is not saved: the next edit to the document replaces it with the file on disk and moves the held edit to the document history (`retryWhen: replaced-on-next-edit`); re-read after that and re-apply the edit if it is still needed. When merging raised a conflict (`pending-conflict`), it is saved after the user resolves the conflict in the app (`conflict-resolved`). In every case, do not repeat the write now: re-read the document before editing it further.+When OpenKnowledge saves a Markdown document, it first compares the file with the version it last agreed with the disk. If another tool changed the file, that change is merged into the document before the save, so the write succeeds and the file holds both edits; re-read the document before editing it further. This covers saves of edits made in the app, idle saves, the save at quit, the in-app agent's whole-document write and the agent write routes. Rename, delete and the other writers do not run this comparison yet. The stale-external-write case above is the exception: when the file holds a version that an earlier agent write replaced, the write returns that 409 instead. If a Markdown save cannot finish safely, the write returns `urn:ok:error:save-held` (503). The body carries `reason` (what holds the save), `retryWhen` (what the server's own save waits for; it is never a cue to repeat the request) and `nextStep: re-read`; in a batch response the same fields appear on that entry's `error`. When the file cannot be read (`pending-unreadable`, with the errno in `causeCode`), keeps changing (`pending-exhausted`, `pending-base-moved`) or the outside change could not be merged (`pending-intake-failed`), the next edit or the idle save within a few minutes saves it (`retryWhen: next-save`). When OpenKnowledge has no agreed version of the file to merge with (`pending-intake-failed-no-base`, or any hold on such a document), the edit is not saved: the next edit to the document replaces it with the file on disk and moves the held edit to the document history (`retryWhen: replaced-on-next-edit`); re-read after that and re-apply the edit if it is still needed. When merging raised a conflict (`pending-conflict`), it is saved after the user resolves the conflict in the app (`conflict-resolved`). In every case, do not repeat the write now: re-read the document before editing it further.++A write to a Mermaid, Excalidraw or plain-text document or to a global or external skill returns its ordinary success response whatever its save does; these writes never return `save-held`. The save compares the file the same way, and what happens shows only in the document, its history and the user's notice. A Mermaid, Excalidraw or plain-text file has no merge: when it changed outside OpenKnowledge, the version being written is kept and the outside version is saved to the document's history. A skill merges an outside change like a Markdown document, and when the merge is refused the version being written is kept and the outside version is saved the same way. When history cannot take a version, it is saved under `~/.ok/edit-backups/discarded/` instead. When neither can take it, or the file keeps changing, cannot be read, or changed to text that is not UTF-8, nothing is written: the save is held and retried, and only the user's notice says so. So after a write to one of these files, re-read it before editing it further, and if it is not what you wrote, look for the other version with `history`. A typed outcome for these writes is planned. Settings files, which the `config` tool reads, follow the same rules when they change outside OpenKnowledge: a valid outside version replaces the user's unsaved settings edits, which are saved first, as soon as OpenKnowledge sees it; an invalid one is only rejected until the next settings save, which saves it to history, or the backup folder, and then writes over it.`conflict.kind` says where the conflict came from, and the kind decides what a resolve does. `merge-native` is a git merge that left unmerged stages in the index. Resolving one stages your choice with git and commits the merge once no `merge-native` conflict is left. `working-tree` is a pull-only overlay collision, pinned to the origin blob it hit. `reconcile` is OpenKnowledge's own three-way merge of the editor against disk, including protected stale saves; no git object holds those stages, so OpenKnowledge snapshots them when it detects the conflict. Resolving a `working-tree` or `reconcile` conflict commits nothing.diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 33d2594f8..50516a720 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -153,8 +153,8 @@ The app runs a collaboration server for the open project. It writes runtime stat| `.ok/local/sync-state.json` | GitHub-sync engine state | In-project, gitignored || `.ok/local/conflicts.json` | Every conflict the app is holding a document for, including conflicts that involve no remote. A row for OpenKnowledge's own merge of the editor against disk embeds up to three full copies of the document body, so **keep this file while any conflict is open**. Deleting it loses those copies. If the app cannot read the file, it renames it to `conflicts.json.corrupt-<timestamp>` and leaves it in place | In-project, gitignored || `.ok/local/stale-external-writes.json` | Recovery snapshot for a rejected stale external save. It can hold the acknowledged, rejected, and retained document text. Protection expires after 30 minutes, but an unresolved snapshot stays until you resolve the conflict | In-project, gitignored |-| `.ok/local/doc-notices.json` | The notice a document shows after both versions of an edit were kept, or a version was saved to the timeline instead of merged: document names, times, and timeline entry ids, never document text. A notice is removed when you dismiss it, when its document is deleted, when the version it names leaves the timeline, or when more than 200 newer notices, counted across all branches, push it out. It follows its document through a rename, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored |-| `.ok/local/receipts.jsonl` | One record per document OpenKnowledge has opened or saved: a hash of the version it and the file last agreed on, its size, and the file's identity and modification time. No document text. OpenKnowledge keeps the same record in memory while it runs, and a save of a Markdown document compares the file with that record first, so an outside edit is merged instead of written over; other writers do not check it yet. After a restart the file is only used to count documents changed while OpenKnowledge was closed. Safe to delete: the next load rebuilds it | In-project, gitignored |+| `.ok/local/doc-notices.json` | The notice a document or settings file shows after both versions of an edit were kept, or a version was saved to its history or the backup folder instead of merged, and, for a document or skill but not a settings file, a separate notice while a save of it is held, removed once that save lands or OpenKnowledge restarts with nothing held: document names, file paths, times, causes, and history entry ids, never document text. A notice is removed when you dismiss it, when its document is deleted, when the version it names leaves the timeline, or when more than 200 newer notices, counted across all branches, push it out. It follows its document through a rename, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored |+| `.ok/local/receipts.jsonl` | One record per document OpenKnowledge has opened or saved: a hash of the version it and the file last agreed on, its size, and the file's identity and modification time. No document text. OpenKnowledge keeps the same record in memory while it runs, and a save of a Markdown, Mermaid, Excalidraw or plain-text document compares the file with that record first, so an outside edit is merged, or saved to history, instead of written over; settings files compare against the last version OpenKnowledge read or wrote instead, and other writers do not check it yet. After a restart the file is only used to count documents changed while OpenKnowledge was closed. Safe to delete: the next load rebuilds it | In-project, gitignored || `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the last detached-spawn error log | In-project, gitignored || `.ok/local/acp-agents.json` | Read, not written: your own list of [custom in-app agents](../features/editor.mdx#add-your-own-in-app-agent), re-read every time the agent catalog is built | In-project, gitignored || `.ok/local/acp-launch-failures.log` | In-app agent launches that failed: when, which agent, why, and the last lines the agent printed before it exited, so a bug report shows the cause without a re-run. Starts over once it passes 256 KB | In-project, gitignored |@@ -169,7 +169,7 @@ The app runs a collaboration server for the open project. It writes runtime stat| `.ok/local/terminal/claude-settings-{mcp,tools,mcp-tools}.json` | Windows-only Claude launch settings written when **Open in Claude** requests MCP or tool preapproval; one of three possible files, overwritten rather than appended on each launch that uses that combination. macOS and Linux pass the same settings inline | In-project, gitignored || `.ok/local/comments/` | [Comments](/docs/features/comments) left on documents, one JSON file each — the note, the passage it quotes, and whether it has been sent | In-project, gitignored || `.ok/worktrees/<branch>/` | Git worktree checkout created when you open a branch in its own window (project switcher); the path is also added to `.git/info/exclude` | In-project, gitignored |-| `.git/ok/` — or `.git/worktrees/<name>/ok/` in a linked worktree, or the enclosing repo's `.git/ok-<slug>/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs; always inside a git admin dir, never in your content tree. Its own `info/exclude` file, written when OpenKnowledge opens the repo, keeps machine-local runtime state — `.ok/local/` and `.ok/worktrees/`, plus the pre-`.ok/local/` equivalents that older projects still keep at the `.ok/` root (`.ok/principal.json`, `.ok/server.lock`, `.ok/cache/`, …) — the `.tmp.<uuid>` files an in-flight atomic write leaves behind, and your project's `.git` when it resolves to a directory inside the project under another name (a `.git.nosync` symlink or a separate git dir), out of every saved version, the way `.ok/.gitignore` keeps them out of git | In-project, gitignored (inside `.git/`) |+| `.git/ok/` — or `.git/worktrees/<name>/ok/` in a linked worktree, or the enclosing repo's `.git/ok-<slug>/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs, plus the versions OpenKnowledge set aside when an outside change could not be merged: of documents, Mermaid, Excalidraw and plain-text files, global and external skills, and the project, per-machine (`.ok/local/config.yml`) and user (`~/.ok/global.yml`) settings files. Those are saved as their own history entries, which `info/exclude` does not filter, so a copy of this folder can carry per-machine settings, your user settings and global skill text; each kind keeps its 50 newest per document, with no time limit. Always inside a git admin dir, never in your content tree. Its own `info/exclude` file, written when OpenKnowledge opens the repo, keeps machine-local runtime state — `.ok/local/` and `.ok/worktrees/`, plus the pre-`.ok/local/` equivalents that older projects still keep at the `.ok/` root (`.ok/principal.json`, `.ok/server.lock`, `.ok/cache/`, …) — the `.tmp.<uuid>` files an in-flight atomic write leaves behind, and your project's `.git` when it resolves to a directory inside the project under another name (a `.git.nosync` symlink or a separate git dir), out of every work-in-progress version, the way `.ok/.gitignore` keeps them out of git | In-project, gitignored (inside `.git/`) |Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off with `telemetry.localSink.enabled: false`; see [Configuration](./configuration.mdx).@@ -203,6 +203,7 @@ Beta writes the `~/.ok/` entries below under `~/.ok-beta/` instead, except the s| `~/.ok/agent-browser/<chat>/` | Only while **Let agent chats use a browser** is on: `npm/`, the folder that chat's browser server starts from, rebuilt each time it launches, and `files/`, everything the browser saves. Removed when you delete the chat in OpenKnowledge; turning the setting off keeps it, and nothing else clears it, so delete the folder yourself to remove every chat's saved files at once | No || `_npx/<hash>/` in the npm cache that launch uses: your own npm cache (`~/.npm` unless your `npm_config_cache` says otherwise) when the agent runs through your system npx, or OpenKnowledge's managed Node.js runtime cache at `~/.ok/runtimes/cache/node` when no usable system Node.js was found and the agent runs on that runtime | Written when OpenKnowledge installs or launches an in-app agent through npx, a custom command such as `npx -y <package>` included, and when the browser server a Claude Code or Codex chat starts while **Let agent chats use a browser** is on installs `@playwright/mcp`. OpenKnowledge repairs the entry only for catalog-managed agents and the browser server, never for custom agent commands or uv-managed adapters. When npm reports that the installed copy is missing as a catalog-managed agent starts, OpenKnowledge installs it again once. When npm reports that the entry is missing its `package.json`, OpenKnowledge deletes that one directory and relaunches the agent once, which installs it again. The browser server's entry is cleared the same way and reinstalled once | No || `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No |+| `~/.ok/edit-backups/discarded/projects/<project>/<document>/`, `~/.ok/edit-backups/discarded/<skill>/` | A copy of a version OpenKnowledge set aside but could not save to the project's history, for example in a project with no shadow repo: the outside version of a Mermaid, Excalidraw or plain-text file, a skill's outside version that could not be merged, or a settings version that was replaced. Files of a project go in a folder for that project (`<project>` is a short hash of its content folder), so two projects with the same file keep separate copies; global and external skills keep one folder each. Each copy is named for the time it was kept, and the five newest per folder stay. The notice on the document, or in Settings, names the file | No || `~/.ok/mcp-status.json` | First-launch MCP consent record | No || `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` and the app's **Help → Report a bug…** dialog (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). Each report from the dialog also gets a small YAML record holding its send state and a secret-redacted copy of the note you wrote, so report history can still show what a report was about. The zip is deleted once the report is sent; the record is kept, and both go when you delete the report from report history. If that record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send, so history still shows it as sent instead of offering to send it again | No || `~/.ok/bin/`, `~/.ok/env.sh` | `PATH` shim (see [Shell and `PATH`](#shell-and-path) above) | No |@@ -297,8 +298,8 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a| `.ok/local/sync-state.json` | GitHub-sync engine state | In-project, gitignored || `.ok/local/conflicts.json` | Every conflict the app is holding a document for, including conflicts that involve no remote. A row for OpenKnowledge's own merge of the editor against disk embeds up to three full copies of the document body, so **keep this file while any conflict is open**. Deleting it loses those copies. If the app cannot read the file, it renames it to `conflicts.json.corrupt-<timestamp>` and leaves it in place | In-project, gitignored || `.ok/local/stale-external-writes.json` | Recovery snapshot for a rejected stale external save. It can hold the acknowledged, rejected, and retained document text. Protection expires after 30 minutes, but an unresolved snapshot stays until you resolve the conflict | In-project, gitignored |-| `.ok/local/doc-notices.json` | The notice a document shows after both versions of an edit were kept, or a version was saved to the timeline instead of merged: document names, times, and timeline entry ids, never document text. A notice is removed when you dismiss it, when its document is deleted, when the version it names leaves the timeline, or when more than 200 newer notices, counted across all branches, push it out. It follows its document through a rename, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored |-| `.ok/local/receipts.jsonl` | One record per document OpenKnowledge has opened or saved: a hash of the version it and the file last agreed on, its size, and the file's identity and modification time. No document text. OpenKnowledge keeps the same record in memory while it runs, and a save of a Markdown document compares the file with that record first, so an outside edit is merged instead of written over; other writers do not check it yet. After a restart the file is only used to count documents changed while OpenKnowledge was closed. Safe to delete: the next load rebuilds it | In-project, gitignored |+| `.ok/local/doc-notices.json` | The notice a document or settings file shows after both versions of an edit were kept, or a version was saved to its history or the backup folder instead of merged, and, for a document or skill but not a settings file, a separate notice while a save of it is held, removed once that save lands or OpenKnowledge restarts with nothing held: document names, file paths, times, causes, and history entry ids, never document text. A notice is removed when you dismiss it, when its document is deleted, when the version it names leaves the timeline, or when more than 200 newer notices, counted across all branches, push it out. It follows its document through a rename, and each branch keeps its own. If the app cannot read the file, it starts with no notices | In-project, gitignored |+| `.ok/local/receipts.jsonl` | One record per document OpenKnowledge has opened or saved: a hash of the version it and the file last agreed on, its size, and the file's identity and modification time. No document text. OpenKnowledge keeps the same record in memory while it runs, and a save of a Markdown, Mermaid, Excalidraw or plain-text document compares the file with that record first, so an outside edit is merged, or saved to history, instead of written over; settings files compare against the last version OpenKnowledge read or wrote instead, and other writers do not check it yet. After a restart the file is only used to count documents changed while OpenKnowledge was closed. Safe to delete: the next load rebuilds it | In-project, gitignored || `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the last detached-spawn error log | In-project, gitignored || `.ok/local/acp-agents.json` | Read, not written: your own list of [custom in-app agents](../features/editor.mdx#add-your-own-in-app-agent), re-read every time the agent catalog is built | In-project, gitignored || `.ok/local/acp-launch-failures.log` | In-app agent launches that failed: when, which agent, why, and the last lines the agent printed before it exited, so a bug report shows the cause without a re-run. Starts over once it passes 256 KB | In-project, gitignored |@@ -310,7 +311,7 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a| `.ok/local/agent-skill/open-knowledge/` | Runtime copy of the OpenKnowledge project skill (`SKILL.md` and `references/`), refreshed before in-app agent processes start. New in-app agent sessions receive this guidance automatically, even when the skill is not installed into an editor | In-project, gitignored with the `local/` ignore rule || `.ok/local/skill-move-retained.json` | Bookkeeping for a skill move between Project and Global scope that could not finish: which destination copy was kept, why, and what the source looked like at the time. Keyed by scope and skill name, one record each. A record clears when a later move of that skill completes, when the copy at the destination stops matching the one recorded, or when you delete that skill at that scope. No document content | In-project, gitignored || `.ok/local/comments/` | [Comments](/docs/features/comments) left on documents, one JSON file each — the note, the passage it quotes, and whether it has been sent | In-project, gitignored |-| `.git/ok/` — or `.git/worktrees/<name>/ok/` in a linked worktree, or the enclosing repo's `.git/ok-<slug>/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs (powers the timeline); always inside a git admin dir, never in your content tree. Its own `info/exclude` file, written when OpenKnowledge opens the repo, keeps machine-local runtime state — `.ok/local/` and `.ok/worktrees/`, plus the pre-`.ok/local/` equivalents that older projects still keep at the `.ok/` root (`.ok/principal.json`, `.ok/server.lock`, `.ok/cache/`, …) — the `.tmp.<uuid>` files an in-flight atomic write leaves behind, and your project's `.git` when it resolves to a directory inside the project under another name (a `.git.nosync` symlink or a separate git dir), out of every saved version, the way `.ok/.gitignore` keeps them out of git | In-project, gitignored (inside `.git/`) |+| `.git/ok/` — or `.git/worktrees/<name>/ok/` in a linked worktree, or the enclosing repo's `.git/ok-<slug>/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs (powers the timeline), plus the versions OpenKnowledge set aside when an outside change could not be merged: of documents, Mermaid, Excalidraw and plain-text files, global and external skills, and the project, per-machine (`.ok/local/config.yml`) and user (`~/.ok/global.yml`) settings files. Those are saved as their own history entries, which `info/exclude` does not filter, so a copy of this folder can carry per-machine settings, your user settings and global skill text; each kind keeps its 50 newest per document, with no time limit. Always inside a git admin dir, never in your content tree. Its own `info/exclude` file, written when OpenKnowledge opens the repo, keeps machine-local runtime state — `.ok/local/` and `.ok/worktrees/`, plus the pre-`.ok/local/` equivalents that older projects still keep at the `.ok/` root (`.ok/principal.json`, `.ok/server.lock`, `.ok/cache/`, …) — the `.tmp.<uuid>` files an in-flight atomic write leaves behind, and your project's `.git` when it resolves to a directory inside the project under another name (a `.git.nosync` symlink or a separate git dir), out of every work-in-progress version, the way `.ok/.gitignore` keeps them out of git | In-project, gitignored (inside `.git/`) |Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off with `telemetry.localSink.enabled: false`; see [Configuration](./configuration.mdx).@@ -345,6 +346,7 @@ Beta writes the `~/.ok/` entries below under `~/.ok-beta/` instead, except the s| `~/.ok/agent-browser/<chat>/` | Only while **Let agent chats use a browser** is on: `npm/`, the folder that chat's browser server starts from, rebuilt each time it launches, and `files/`, everything the browser saves. Removed when you delete the chat in OpenKnowledge; turning the setting off keeps it, and nothing else clears it, so delete the folder yourself to remove every chat's saved files at once | No || `_npx/<hash>/` in the npm cache that launch uses: your own npm cache (`~/.npm` unless your `npm_config_cache` says otherwise) when the agent runs through your system npx, or OpenKnowledge's managed Node.js runtime cache at `~/.ok/runtimes/cache/node` when no usable system Node.js was found and the agent runs on that runtime | Written when OpenKnowledge installs or launches an in-app agent through npx, a custom command such as `npx -y <package>` included, and when the browser server a Claude Code or Codex chat starts while **Let agent chats use a browser** is on installs `@playwright/mcp`. OpenKnowledge repairs the entry only for catalog-managed agents and the browser server, never for custom agent commands or uv-managed adapters. When npm reports that the installed copy is missing as a catalog-managed agent starts, OpenKnowledge installs it again once. When npm reports that the entry is missing its `package.json`, OpenKnowledge deletes that one directory and relaunches the agent once, which installs it again. The browser server's entry is cleared the same way and reinstalled once | No || `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No |+| `~/.ok/edit-backups/discarded/projects/<project>/<document>/`, `~/.ok/edit-backups/discarded/<skill>/` | A copy of a version OpenKnowledge set aside but could not save to the project's history, for example in a project with no shadow repo: the outside version of a Mermaid, Excalidraw or plain-text file, a skill's outside version that could not be merged, or a settings version that was replaced. Files of a project go in a folder for that project (`<project>` is a short hash of its content folder), so two projects with the same file keep separate copies; global and external skills keep one folder each. Each copy is named for the time it was kept, and the five newest per folder stay. The notice on the document, or in Settings, names the file | No || `~/.ok/logs/` | CLI logs (`cli.<date>.log`), size- and age-capped | No || `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` — the desktop app's **Help → Report a bug…** dialog writes here too (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). A report filed from the dialog also leaves a small YAML record beside its bundle, holding the report's send state and a secret-redacted copy of the note you wrote so report history can name it. That record outlives the bundle: the zip is deleted once the report is sent, and the record is kept until you delete the report from report history. If the record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send. That marker holds only the send time and the report's reference, never your note, and it is removed with the rest of the report | No |diff --git a/packages/app/package.json b/packages/app/package.jsonindex 4986b8061..cbea348d9 100644--- a/packages/app/package.json+++ b/packages/app/package.json@@ -68,7 +68,7 @@{"name": "all JS chunks combined (gzipped)","path": "dist/assets/*.js",- "limit": "9.17 MB",+ "limit": "9.18 MB","gzip": true,"running": false},diff --git a/packages/app/src/components/DocChangeNotice.dom.test.tsx b/packages/app/src/components/DocChangeNotice.dom.test.tsxindex 70e09858e..789b82818 100644--- a/packages/app/src/components/DocChangeNotice.dom.test.tsx+++ b/packages/app/src/components/DocChangeNotice.dom.test.tsx@@ -119,6 +119,30 @@ describe('DocChangeNotice', () => {notice: moved('n-ours', 'folder/plan', 'ours'),says: "Edits to plan.md kept from the last time this branch was open could not be merged, so the file's version stayed.",},+ {+ notice: {+ ...moved('n-engineless', 'folder/plan', 'theirs'),+ file: 'folder/flow.mmd',+ reason: 'no-merge-engine',+ },+ says: 'An outside change to flow.mmd could not be merged, so this version stayed. The outside version is in the timeline.',+ },+ {+ notice: {+ ...moved('n-settings-applied', 'folder/plan', 'ours'),+ file: '.ok/config.yml',+ reason: 'outside-settings-applied',+ },+ says: "Settings in config.yml changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet.",+ },+ {+ notice: {+ ...moved('n-settings-invalid', 'folder/plan', 'theirs'),+ file: '.okignore',+ reason: 'outside-settings-invalid',+ },+ says: "An outside change to .okignore was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet.",+ },];for (const { notice, says } of cases) {serverNotices = [notice];@@ -128,6 +152,91 @@ describe('DocChangeNotice', () => {}});+ test('a version kept in the backup folder, and a save that is held, say where the version went or why nothing was saved', async () => {+ const backup = '~/.ok/edit-backups/discarded/folder__flow.mmd/2026-10-21T10-00-00-000Z.mmd';+ const common = {+ docName: 'folder/flow.mmd',+ file: 'folder/flow.mmd',+ firstAt: AT,+ lastAt: AT,+ events: 1,+ entries: [],+ };+ const cases: Array<{ notice: DocNoticeWire; says: string }> = [+ {+ notice: {+ ...common,+ id: 'n-backup',+ kind: 'moved-to-backup',+ side: 'theirs',+ reason: 'no-merge-engine',+ backup,+ },+ says: `An outside change to flow.mmd could not be merged, so this version stayed. The outside version was saved to ${backup}.`,+ },+ {+ notice: { ...common, id: 'n-held-none', kind: 'save-held', cause: 'no-history-or-backup' },+ says: 'flow.mmd was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again.',+ },+ {+ notice: { ...common, id: 'n-held-busy', kind: 'save-held', cause: 'keeps-changing' },+ says: 'flow.mmd was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again.',+ },+ {+ notice: { ...common, id: 'n-held-bytes', kind: 'save-held', cause: 'not-utf8' },+ says: 'flow.mmd was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes.',+ },+ ];+ for (const { notice, says } of cases) {+ serverNotices = [notice];+ renderNotice('folder/flow.mmd');+ const shown = await findNotice();+ expect(shown.textContent).toContain(says);+ expect(within(shown).queryByRole('button', { name: 'Open timeline' })).toBeNull();+ cleanup();+ }+ });++ test('a held save shows above a kept-version notice on the same document, and each dismisses on its own', async () => {+ serverNotices = [+ moved('n-kept', 'notes', 'theirs'),+ {+ id: 'n-held',+ docName: 'notes',+ file: 'notes.md',+ kind: 'save-held',+ cause: 'unreadable',+ firstAt: AT,+ lastAt: AT,+ events: 1,+ entries: [],+ },+ ];+ renderNotice('notes');++ await waitFor(() =>+ expect(screen.getAllByRole('region', { name: 'File change notice' })).toHaveLength(2),+ );+ const [held, kept] = screen.getAllByRole('region', { name: 'File change notice' });+ expect(held?.textContent).toContain(+ 'notes.md was not saved because it could not be read to compare it with outside changes, so the file was not written over.',+ );+ expect(kept?.textContent).toContain('An outside change to notes.md could not be merged');+ await waitFor(() =>+ expect(screen.getByRole('status').textContent).toBe(+ 'notes.md was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again. An outside change to notes.md could not be merged, so this version stayed. The outside version is in the timeline.',+ ),+ );++ fireEvent.click(within(held as HTMLElement).getByRole('button', { name: 'Dismiss notice' }));++ await waitFor(() => expect(dismissBodies).toEqual([{ docName: 'notes', id: 'n-held' }]));+ expect(screen.getAllByRole('region', { name: 'File change notice' })).toHaveLength(1);+ expect(screen.getByRole('region', { name: 'File change notice' }).textContent).toContain(+ 'An outside change to notes.md could not be merged',+ );+ });+test('a document with no notice shows nothing but keeps an empty status region ready', async () => {serverNotices = [bothKept('n-other', 'other')];renderNotice('notes');diff --git a/packages/app/src/components/DocChangeNotice.tsx b/packages/app/src/components/DocChangeNotice.tsxindex 0b126a2d2..d3a35e405 100644--- a/packages/app/src/components/DocChangeNotice.tsx+++ b/packages/app/src/components/DocChangeNotice.tsx@@ -5,25 +5,67 @@ import { type KeyboardEvent, useEffect, useRef, useState } from 'react';import { requestDocPanelTab } from '@/components/doc-panel-events';import { SkillModeBanner } from '@/components/SkillModeBanner';import { Button } from '@/components/ui/button';-import { useDocNotice } from '@/hooks/use-doc-notices';+import { useDocNotices } from '@/hooks/use-doc-notices';+import { saveHeldMessage } from '@/lib/save-held-message';import { useSingleFileMode } from '@/lib/single-file-mode';const announcedNoticeIds = new Set<string>();const EDITOR_FOCUS_TARGETS = ['[contenteditable="true"]', '.cm-content'] as const;+type NoticeFileLabel = 'name' | 'path';++function noticeFileText(notice: DocNoticeWire, fileLabel: NoticeFileLabel): string {+ return fileLabel === 'path' ? notice.file : (notice.file.split('/').pop() ?? notice.file);+}+function NoticeMessage({notice,canOpenTimeline,+ fileLabel,}: {notice: DocNoticeWire;canOpenTimeline: boolean;+ fileLabel: NoticeFileLabel;}) {+ const { t } = useLingui();const fileName = (<span translate="no" className="font-medium text-foreground">- {notice.file.split('/').pop() ?? notice.file}+ {noticeFileText(notice, fileLabel)}</span>);+ if (notice.kind === 'save-held') {+ return t(saveHeldMessage(notice.cause, noticeFileText(notice, fileLabel)));+ }+ if (notice.kind === 'moved-to-backup') {+ const backupPath = (+ <span translate="no" className="font-medium text-foreground break-all">+ {notice.backup}+ </span>+ );+ if (notice.reason === 'outside-settings-applied') {+ return (+ <Trans>+ Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change+ you were making was saved to {backupPath}.+ </Trans>+ );+ }+ if (notice.reason === 'outside-settings-invalid') {+ return (+ <Trans>+ An outside change to {fileName} was not valid settings, so your settings stayed. A copy of+ the outside version was saved to {backupPath}.+ </Trans>+ );+ }+ return (+ <Trans>+ An outside change to {fileName} could not be merged, so this version stayed. The outside+ version was saved to {backupPath}.+ </Trans>+ );+ }if (notice.kind === 'both-kept') {if (notice.kept.duplicated > 0) {return (@@ -52,6 +94,22 @@ function NoticeMessage({</Trans>);}+ if (notice.reason === 'outside-settings-applied') {+ return (+ <Trans>+ Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you+ were making was kept in this project's history, which the app cannot show yet.+ </Trans>+ );+ }+ if (notice.reason === 'outside-settings-invalid') {+ return (+ <Trans>+ An outside change to {fileName} was not valid settings, so your settings stayed. A copy of+ the outside version was kept in this project's history, which the app cannot show yet.+ </Trans>+ );+ }if (notice.side === 'theirs') {return canOpenTimeline ? (<Trans>@@ -89,34 +147,35 @@ function focusEditorWithin(scope: HTMLElement | null): void {scope.closest<HTMLElement>('[data-editor-region]')?.focus();}-export function DocChangeNotice({- docName,- timelineAvailable,-}: {- docName: string;- timelineAvailable: boolean;-}) {+interface NoticeSectionProps {+ notice: DocNoticeWire;+ canOpenTimeline: boolean;+ fileLabel: NoticeFileLabel;+ onDismissFocus?: () => void;+ messageRef: (node: HTMLSpanElement | null) => void;+ dismiss: (notice: DocNoticeWire) => void;+}++function NoticeSection({+ notice,+ canOpenTimeline,+ fileLabel,+ onDismissFocus,+ messageRef,+ dismiss,+}: NoticeSectionProps) {const { t } = useLingui();- const { notice, dismiss } = useDocNotice(docName);- const singleFile = useSingleFileMode();const sectionRef = useRef<HTMLElement>(null);- const messageRef = useRef<HTMLSpanElement>(null);- const [announcement, setAnnouncement] = useState('');- const canOpenTimeline = timelineAvailable && !singleFile;-- const noticeId = notice?.id ?? null;- useEffect(() => {- if (noticeId === null || announcedNoticeIds.has(noticeId)) return;- announcedNoticeIds.add(noticeId);- setAnnouncement(messageRef.current?.textContent ?? '');- }, [noticeId]);function handleDismiss() {- if (notice === null) return;const hadFocus = sectionRef.current?.contains(document.activeElement) ?? false;const scope = sectionRef.current?.parentElement ?? null;dismiss(notice);- if (hadFocus) requestAnimationFrame(() => focusEditorWithin(scope));+ if (!hadFocus) return;+ requestAnimationFrame(() => {+ if (onDismissFocus) onDismissFocus();+ else focusEditorWithin(scope);+ });}function handleKeyDown(event: KeyboardEvent<HTMLElement>) {@@ -125,52 +184,95 @@ export function DocChangeNotice({handleDismiss();}+ return (+ <section+ ref={sectionRef}+ aria-label={t`File change notice`}+ data-slot="doc-change-notice"+ data-testid="doc-change-notice"+ onKeyDown={handleKeyDown}+ className="shrink-0"+ >+ <SkillModeBanner+ icon={<History className="size-4" aria-hidden />}+ clampLines={false}+ actions={+ <>+ {canOpenTimeline && notice.entries.length > 0 ? (+ <Button+ variant="link"+ size="sm"+ className="h-auto px-1"+ onClick={() => requestDocPanelTab('timeline', { focus: 'panel' })}+ >+ {t`Open timeline`}+ </Button>+ ) : null}+ <Button+ variant="ghost"+ size="icon"+ className="size-6 text-muted-foreground"+ aria-label={t`Dismiss notice`}+ onClick={handleDismiss}+ >+ <X className="size-3.5" aria-hidden />+ </Button>+ </>+ }+ >+ <span ref={messageRef}>+ <NoticeMessage notice={notice} canOpenTimeline={canOpenTimeline} fileLabel={fileLabel} />+ </span>+ </SkillModeBanner>+ </section>+ );+}++export function DocChangeNotice({+ docName,+ timelineAvailable,+ fileLabel = 'name',+ onDismissFocus,+}: {+ docName: string;+ timelineAvailable: boolean;+ fileLabel?: NoticeFileLabel;+ onDismissFocus?: () => void;+}) {+ const { notices, dismiss } = useDocNotices(docName);+ const singleFile = useSingleFileMode();+ const messages = useRef(new Map<string, HTMLSpanElement>());+ const [announcement, setAnnouncement] = useState('');+ const canOpenTimeline = timelineAvailable && !singleFile;++ useEffect(() => {+ const fresh = notices.filter((notice) => !announcedNoticeIds.has(notice.id));+ if (fresh.length === 0) return;+ for (const notice of fresh) announcedNoticeIds.add(notice.id);+ setAnnouncement(+ fresh.map((notice) => messages.current.get(notice.id)?.textContent ?? '').join(' '),+ );+ }, [notices]);+return (<><span role="status" className="sr-only">{announcement}</span>- {notice === null ? null : (- <section- ref={sectionRef}- aria-label={t`File change notice`}- data-testid="doc-change-notice"- onKeyDown={handleKeyDown}- className="shrink-0"- >- <SkillModeBanner- icon={<History className="size-4" aria-hidden />}- clampLines={false}- actions={- <>- {canOpenTimeline && notice.entries.length > 0 ? (- <Button- variant="link"- size="sm"- className="h-auto px-1"- onClick={() => requestDocPanelTab('timeline', { focus: 'panel' })}- >- {t`Open timeline`}- </Button>- ) : null}- <Button- variant="ghost"- size="icon"- className="size-6 text-muted-foreground"- aria-label={t`Dismiss notice`}- onClick={handleDismiss}- >- <X className="size-3.5" aria-hidden />- </Button>- </>- }- >- <span ref={messageRef}>- <NoticeMessage notice={notice} canOpenTimeline={canOpenTimeline} />- </span>- </SkillModeBanner>- </section>- )}+ {notices.map((notice) => (+ <NoticeSection+ key={notice.id}+ notice={notice}+ canOpenTimeline={canOpenTimeline}+ fileLabel={fileLabel}+ onDismissFocus={onDismissFocus}+ messageRef={(node) => {+ if (node === null) messages.current.delete(notice.id);+ else messages.current.set(notice.id, node);+ }}+ dismiss={dismiss}+ />+ ))}</>);}diff --git a/packages/app/src/components/TimelinePanel.dom.test.tsx b/packages/app/src/components/TimelinePanel.dom.test.tsxindex cfe0d4090..8c61ad328 100644--- a/packages/app/src/components/TimelinePanel.dom.test.tsx+++ b/packages/app/src/components/TimelinePanel.dom.test.tsx@@ -144,6 +144,12 @@ const SURFACED_KINDS: ParsedCheckpoint[] = [size: 12,metadata: { side: 'theirs', reason: 'check-failed' },},+ {+ kind: 'external-change-no-engine',+ docName: 'flow.mmd',+ size: 12,+ metadata: { side: 'theirs', fileType: 'mermaid' },+ },];const MERGE_VERSION_ROWS: Array<{ checkpoint: ParsedCheckpoint; title: string; side: string }> = [{@@ -186,6 +192,16 @@ const MERGE_VERSION_ROWS: Array<{ checkpoint: ParsedCheckpoint; title: string; stitle: 'Not merged',side: 'Version in OpenKnowledge',},+ {+ checkpoint: {+ kind: 'external-change-no-engine',+ docName: 'flow.mmd',+ size: 12,+ metadata: { side: 'theirs', fileType: 'mermaid' },+ },+ title: 'Not merged',+ side: 'Outside version',+ },];const AUTO_CONSOLIDATION: ParsedCheckpoint = {kind: 'auto-consolidation',diff --git a/packages/app/src/components/TimelinePanel.tsx b/packages/app/src/components/TimelinePanel.tsxindex 9434ef791..de0a89937 100644--- a/packages/app/src/components/TimelinePanel.tsx+++ b/packages/app/src/components/TimelinePanel.tsx@@ -155,7 +155,8 @@ function classifyEntry(entry: TimelineEntry): EntryDescriptor {const checkpoint = entry.checkpoint;if (checkpoint?.kind === 'external-change-both-kept' ||- checkpoint?.kind === 'external-change-kept-live'+ checkpoint?.kind === 'external-change-kept-live' ||+ checkpoint?.kind === 'external-change-no-engine') {return { kind: 'merge-version', side: checkpoint.metadata.side };}@@ -181,7 +182,12 @@ function displayAuthor(entry: TimelineEntry): string {if (entry.checkpoint?.kind === 'external-change-both-kept') {return t`Before an outside change was merged`;}- if (entry.checkpoint?.kind === 'external-change-kept-live') return t`Not merged`;+ if (+ entry.checkpoint?.kind === 'external-change-kept-live' ||+ entry.checkpoint?.kind === 'external-change-no-engine'+ ) {+ return t`Not merged`;+ }return t`Recovered content`;}if (entry.type === 'upstream') return t`Upstream sync`;diff --git a/packages/app/src/components/settings/OkignoreSection.dom.test.tsx b/packages/app/src/components/settings/OkignoreSection.dom.test.tsxindex 8a7822a80..99e7e45b1 100644--- a/packages/app/src/components/settings/OkignoreSection.dom.test.tsx+++ b/packages/app/src/components/settings/OkignoreSection.dom.test.tsx@@ -324,6 +324,18 @@ describe('OkignoreSection runtime behavior', () => {'Pattern syntax error (line 3): bad glob',);+ act(() => {+ emitConfigValidationRejected({+ docName: '__config__/okignore',+ error: { code: 'SAVE_HELD', cause: 'keeps-changing', file: '.okignore' },+ } as never);+ });+ await waitFor(() =>+ expect(screen.getByTestId('settings-okignore-rejection-banner').textContent).toContain(+ 'was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again.',+ ),+ );+act(() => {emitConfigIgnoreNestedError({ path: 'nested/.okignore', error: 'parse failed' } as never);});diff --git a/packages/app/src/components/settings/OkignoreSection.tsx b/packages/app/src/components/settings/OkignoreSection.tsxindex b34336304..308521643 100644--- a/packages/app/src/components/settings/OkignoreSection.tsx+++ b/packages/app/src/components/settings/OkignoreSection.tsx@@ -37,6 +37,7 @@ import { Skeleton } from '@/components/ui/skeleton';import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';import { subscribeToConfigIgnoreNestedError } from '@/lib/config-ignore-nested-error-events';import { subscribeToConfigValidationRejected } from '@/lib/config-validation-events';+import { saveHeldRejection } from '@/lib/save-held-message';import { cn } from '@/lib/utils';import {appendPattern,@@ -153,12 +154,13 @@ function OkignoreSectionBody({ binding }: { binding: OkignoreBinding }) {useEffect(() => {return binding.subscribeRejection(({ error }) => {const detail = pickOkignoreDetail(error);- const message = detail?.detail ?? humanFormat(error);+ const held = saveHeldRejection(error);+ const message = held === null ? (detail?.detail ?? humanFormat(error)) : t(held);setRejection({ message, lineNumber: detail?.lineNumber, ts: Date.now() });if (rejectionTimerRef.current) clearTimeout(rejectionTimerRef.current);rejectionTimerRef.current = setTimeout(() => setRejection(null), REJECTION_BANNER_MS);});- }, [binding]);+ }, [binding, t]);useEffect(() => {return subscribeToConfigIgnoreNestedError((event) => {diff --git a/packages/app/src/components/settings/SettingsConfigNotices.dom.test.tsx b/packages/app/src/components/settings/SettingsConfigNotices.dom.test.tsxnew file mode 100644index 000000000..28af3ada5--- /dev/null+++ b/packages/app/src/components/settings/SettingsConfigNotices.dom.test.tsx@@ -0,0 +1,166 @@+import type { DocNoticeWire } from '@inkeep/open-knowledge-core/schemas/api';+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import { DocNoticesProvider } from '@/hooks/use-doc-notices';+import { SingleFileModeProvider } from '@/lib/single-file-mode';+import { SettingsConfigNotices } from './SettingsConfigNotices';++const AT = '2026-10-20T12:00:00.000Z';++function settingsNotice(+ id: string,+ docName: string,+ file: string,+ side: 'ours' | 'theirs',+ reason: 'outside-settings-applied' | 'outside-settings-invalid',+): Extract<DocNoticeWire, { kind: 'moved-to-history' }> {+ return {+ id,+ docName,+ file,+ kind: 'moved-to-history',+ side,+ reason,+ firstAt: AT,+ lastAt: AT,+ events: 1,+ entries: ['a'.repeat(40)],+ };+}++let serverNotices: DocNoticeWire[] = [];+let dismissBodies: unknown[] = [];+let originalFetch: typeof globalThis.fetch;++beforeEach(() => {+ originalFetch = globalThis.fetch;+ serverNotices = [];+ dismissBodies = [];+ globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {+ const url = typeof input === 'string' ? input : input.toString();+ if (url === '/api/doc-notices/dismiss') {+ const body = JSON.parse(String(init?.body)) as { id: string };+ dismissBodies.push(body);+ serverNotices = serverNotices.filter((notice) => notice.id !== body.id);+ return Promise.resolve(Response.json({ dismissed: true }));+ }+ if (url === '/api/doc-notices') {+ return Promise.resolve(Response.json({ notices: serverNotices }));+ }+ return Promise.resolve(new Response(null, { status: 404 }));+ }) as never;+});++afterEach(() => {+ globalThis.fetch = originalFetch;+ cleanup();+});++const onDismissFocus = vi.fn();++function renderSettingsNotices() {+ return render(+ <SingleFileModeProvider>+ <DocNoticesProvider>+ <SettingsConfigNotices onDismissFocus={onDismissFocus} />+ </DocNoticesProvider>+ </SingleFileModeProvider>,+ );+}++describe('SettingsConfigNotices', () => {+ test('shows the notice of each settings file that changed outside, with no timeline to open', async () => {+ serverNotices = [+ settingsNotice(+ 'n-project',+ '__config__/project',+ '.ok/config.yml',+ 'ours',+ 'outside-settings-applied',+ ),+ settingsNotice(+ 'n-ignore',+ '__config__/okignore',+ '.okignore',+ 'theirs',+ 'outside-settings-invalid',+ ),+ ];+ renderSettingsNotices();++ const notices = await screen.findAllByRole('region', { name: 'File change notice' });+ expect(notices.map((notice) => notice.textContent)).toEqual([+ expect.stringContaining(+ "Settings in .ok/config.yml changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet.",+ ),+ expect.stringContaining(+ "An outside change to .okignore was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet.",+ ),+ ]);+ expect(screen.queryByRole('button', { name: 'Open timeline' })).toBeNull();+ });++ test('names each settings file by its path, so the shared and the per-machine config.yml differ, and says where a backup went', async () => {+ serverNotices = [+ settingsNotice(+ 'n-project',+ '__config__/project',+ '.ok/config.yml',+ 'ours',+ 'outside-settings-applied',+ ),+ {+ ...settingsNotice(+ 'n-local',+ '__local__/project',+ '.ok/local/config.yml',+ 'theirs',+ 'outside-settings-invalid',+ ),+ kind: 'moved-to-backup',+ entries: [],+ backup: '~/.ok/edit-backups/discarded/__local____project/2026-10-21T10-00-00-000Z.yml',+ },+ ];+ renderSettingsNotices();++ const notices = await screen.findAllByRole('region', { name: 'File change notice' });+ expect(notices.map((notice) => notice.textContent)).toEqual([+ expect.stringContaining('Settings in .ok/config.yml changed outside OpenKnowledge'),+ expect.stringContaining(+ 'An outside change to .ok/local/config.yml was not valid settings, so your settings stayed. A copy of the outside version was saved to ~/.ok/edit-backups/discarded/__local____project/2026-10-21T10-00-00-000Z.yml.',+ ),+ ]);+ });++ test('ignores notices for documents that are not settings files', async () => {+ serverNotices = [+ settingsNotice('n-doc', 'notes/plan', 'notes/plan.md', 'theirs', 'outside-settings-invalid'),+ ];+ renderSettingsNotices();++ await waitFor(() => expect(globalThis.fetch).toHaveBeenCalled());+ expect(screen.queryByRole('region', { name: 'File change notice' })).toBeNull();+ });++ test('Dismiss removes the notice and tells the server which one it was', async () => {+ serverNotices = [+ settingsNotice(+ 'n-user',+ '__user__/config.yml',+ '~/.ok/config.yml',+ 'ours',+ 'outside-settings-applied',+ ),+ ];+ renderSettingsNotices();++ const notice = await screen.findByRole('region', { name: 'File change notice' });+ fireEvent.click(within(notice).getByRole('button', { name: 'Dismiss notice' }));++ await waitFor(() =>+ expect(screen.queryByRole('region', { name: 'File change notice' })).toBeNull(),+ );+ expect(dismissBodies).toEqual([{ docName: '__user__/config.yml', id: 'n-user' }]);+ });+});diff --git a/packages/app/src/components/settings/SettingsConfigNotices.tsx b/packages/app/src/components/settings/SettingsConfigNotices.tsxnew file mode 100644index 000000000..5448740b3--- /dev/null+++ b/packages/app/src/components/settings/SettingsConfigNotices.tsx@@ -0,0 +1,21 @@+import { CONFIG_DOC_NAMES } from '@inkeep/open-knowledge-core/constants/cc1';+import { DocChangeNotice } from '@/components/DocChangeNotice';++export function SettingsConfigNotices({ onDismissFocus }: { onDismissFocus: () => void }) {+ return (+ <div+ data-testid="settings-config-notices"+ className="has-[section]:-mx-6 has-[section]:-mt-6 has-[section]:mb-6"+ >+ {CONFIG_DOC_NAMES.map((docName) => (+ <DocChangeNotice+ key={docName}+ docName={docName}+ timelineAvailable={false}+ fileLabel="path"+ onDismissFocus={onDismissFocus}+ />+ ))}+ </div>+ );+}diff --git a/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx b/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsxindex 1156129dd..175cad6de 100644--- a/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx+++ b/packages/app/src/components/settings/SettingsDialogBody.dom.test.tsx@@ -15,6 +15,7 @@ import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-libraimport userEvent from '@testing-library/user-event';import { ThemeProvider, useTheme } from 'next-themes';import type { ReactNode } from 'react';+import { toast } from 'sonner';import { afterEach, describe, expect, type Mock, test, vi } from 'vitest';import { TooltipProvider } from '@/components/ui/tooltip';import { ConfigContext, type ConfigContextValue } from '@/lib/config-context';@@ -405,6 +406,48 @@ describe('SettingsDialogBody preferences runtime', () => {});expectVisualClassTokens(attachmentField?.className, ['animate-settings-flash']);});++ test('a held settings save shows its cause and the file it names where other rejections show', async () => {+ const shown = vi.spyOn(toast, 'error');+ const { binding } = makeBinding();+ await renderPreferences(binding);++ act(() => {+ emitConfigValidationRejected({+ v: 1,+ ch: 'config-validation-rejected',+ seq: 3,+ docName: CONFIG_DOC_NAME_USER,+ error: { code: 'SAVE_HELD', cause: 'not-utf8', file: '~/.ok/global.yml' },+ });+ });++ await waitFor(() =>+ expect(shown).toHaveBeenCalledWith(+ '~/.ok/global.yml was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes.',+ { duration: 8000 },+ ),+ );++ act(() => {+ emitConfigValidationRejected({+ v: 1,+ ch: 'config-validation-rejected',+ seq: 4,+ docName: CONFIG_DOC_NAME_USER,+ error: { code: 'SAVE_HELD', cause: 'keeps-changing', file: '~/.ok/global.yml' },+ });+ });++ await waitFor(() =>+ expect(shown).toHaveBeenLastCalledWith(+ '~/.ok/global.yml was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again.',+ { duration: 8000 },+ ),+ );+ expect(shown).toHaveBeenCalledTimes(2);+ shown.mockRestore();+ });});async function openLanguagePicker(user: ReturnType<typeof userEvent.setup>) {diff --git a/packages/app/src/components/settings/SettingsDialogShell.dom.test.tsx b/packages/app/src/components/settings/SettingsDialogShell.dom.test.tsxindex 88603311f..2f3191a20 100644--- a/packages/app/src/components/settings/SettingsDialogShell.dom.test.tsx+++ b/packages/app/src/components/settings/SettingsDialogShell.dom.test.tsx@@ -1,4 +1,5 @@import type { ConfigBinding, OkignoreBinding } from '@inkeep/open-knowledge-core';+import type { DocNoticeWire } from '@inkeep/open-knowledge-core/schemas/api';import { act, cleanup, render, screen, waitFor } from '@testing-library/react';import userEvent from '@testing-library/user-event';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';@@ -120,6 +121,8 @@ vi.doMock('@/lib/handoff/use-claude-desktop-integration', () => ({}));const { SettingsDialogShell } = await import('./SettingsDialogShell');+const { DocNoticesProvider } = await import('@/hooks/use-doc-notices');+const { SingleFileModeProvider } = await import('@/lib/single-file-mode');const SENTINEL_USER_BINDING = {current: () => ({}) as never,@@ -413,3 +416,92 @@ describe('SettingsDialogShell userBinding gating (Tier-3 mount)', () => {).toEqual(['components/settings/settings-search-index.ts']);});});++describe('a settings file notice inside the Settings dialog', () => {+ const NOTICE: DocNoticeWire = {+ id: 'n-local',+ docName: '__local__/project',+ file: '.ok/local/config.yml',+ kind: 'moved-to-history',+ side: 'ours',+ reason: 'outside-settings-applied',+ firstAt: '2026-10-21T10:00:00.000Z',+ lastAt: '2026-10-21T10:00:00.000Z',+ events: 1,+ entries: ['a'.repeat(40)],+ };+ let originalFetch: typeof globalThis.fetch;+ let serverNotices: DocNoticeWire[] = [];+ let consoleErrorSpy: ReturnType<typeof vi.spyOn>;++ beforeEach(() => {+ resetProbe();+ mockBodyMode = 'probe';+ mockProjectConfig = { contentRules: { markdownlint: { enabled: true } } };+ serverNotices = [NOTICE];+ originalFetch = globalThis.fetch;+ globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {+ const url = typeof input === 'string' ? input : input.toString();+ if (url === '/api/doc-notices/dismiss') {+ const body = JSON.parse(String(init?.body)) as { id: string };+ serverNotices = serverNotices.filter((notice) => notice.id !== body.id);+ return Promise.resolve(Response.json({ dismissed: true }));+ }+ if (url === '/api/doc-notices') {+ return Promise.resolve(Response.json({ notices: serverNotices }));+ }+ return Promise.resolve(new Response(null, { status: 404 }));+ }) as never;+ consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});+ });++ afterEach(() => {+ globalThis.fetch = originalFetch;+ cleanup();+ consoleErrorSpy.mockRestore();+ });++ function renderWithNotices(onOpenChange: (open: boolean) => void) {+ return render(+ <SingleFileModeProvider>+ <DocNoticesProvider>+ <SettingsDialogShell open onOpenChange={onOpenChange} />+ </DocNoticesProvider>+ </SingleFileModeProvider>,+ );+ }++ test('names the settings file by its path, sits first in the content tab order, and Escape on it dismisses only the notice', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ renderWithNotices(onOpenChange);++ const notice = await screen.findByRole('region', { name: 'File change notice' });+ expect(notice.textContent).toContain('Settings in .ok/local/config.yml changed outside');+ const content = screen.getByRole('region', { name: 'Settings content' });+ content.focus();+ await user.tab();+ expect(notice.contains(document.activeElement)).toBe(true);++ await user.keyboard('{Escape}');++ await waitFor(() =>+ expect(screen.queryByRole('region', { name: 'File change notice' })).toBeNull(),+ );+ expect(onOpenChange).not.toHaveBeenCalled();+ expect(screen.getByRole('dialog')).toBeTruthy();+ await waitFor(() => expect(document.activeElement).toBe(content));+ });++ test('Escape anywhere else in the dialog still closes it', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ renderWithNotices(onOpenChange);+ await screen.findByRole('region', { name: 'File change notice' });++ screen.getByRole('region', { name: 'Settings content' }).focus();+ await user.keyboard('{Escape}');++ expect(onOpenChange).toHaveBeenCalledWith(false);+ });+});diff --git a/packages/app/src/components/settings/SettingsDialogShell.tsx b/packages/app/src/components/settings/SettingsDialogShell.tsxindex dc67b3570..76fb5f3c5 100644--- a/packages/app/src/components/settings/SettingsDialogShell.tsx+++ b/packages/app/src/components/settings/SettingsDialogShell.tsx@@ -6,6 +6,7 @@ import { SHOW_INSTALL_SKILL } from '@inkeep/open-knowledge-core/constants/featurimport { Plural, Trans, useLingui } from '@lingui/react/macro';import { Suspense, useEffect, useRef, useState, useSyncExternalStore } from 'react';import { matchesCommandQuery, splitTextByQueryMatches } from '@/components/command-palette-search';+import { SettingsConfigNotices } from '@/components/settings/SettingsConfigNotices';import { SettingsDialogBodyLazy } from '@/components/settings/SettingsDialogBodyLazy';import { SettingsDialogErrorBoundary } from '@/components/settings/SettingsDialogErrorBoundary';import { UPDATE_CHECKING_NOTICE_ID } from '@/components/UpdateNotices.shared';@@ -479,7 +480,9 @@ function SettingsDialogFrame({onEscapeKeyDown={(event) => {if (event.target instanceof Element &&- event.target.closest('[data-slot="combobox-chip-input"][aria-expanded="true"]')+ event.target.closest(+ '[data-slot="combobox-chip-input"][aria-expanded="true"], [data-slot="doc-change-notice"]',+ )) {event.preventDefault();}@@ -507,6 +510,7 @@ function SettingsDialogFrame({// biome-ignore lint/a11y/noNoninteractiveTabindex: this scrollable content section must be focusable so keyboard users can scroll long settings pages.tabIndex={0}>+ <SettingsConfigNotices onDismissFocus={() => contentRef.current?.focus()} /><SettingsDialogErrorBoundary key={shownId}><Suspense fallback={<SettingsContentSkeleton />}><SettingsDialogBodyLazydiff --git a/packages/app/src/components/settings/schema-section.tsx b/packages/app/src/components/settings/schema-section.tsxindex 94171cd85..416453816 100644--- a/packages/app/src/components/settings/schema-section.tsx+++ b/packages/app/src/components/settings/schema-section.tsx@@ -5,11 +5,13 @@ import {CONFIG_DOC_NAME_PROJECT,CONFIG_DOC_NAME_USER,} from '@inkeep/open-knowledge-core/constants/cc1';+import { useLingui } from '@lingui/react/macro';import { Fragment, type ReactNode, useEffect, useRef, useState } from 'react';import type { FieldPath } from 'react-hook-form';import { toast } from 'sonner';import { Form } from '@/components/ui/form';import { subscribeToConfigValidationRejected } from '@/lib/config-validation-events';+import { saveHeldRejection } from '@/lib/save-held-message';import { firstIssuePath, type Scope, SettingsField } from './field-controls';import type { SettingsScope } from './ScopeBadge';import { SettingsSectionHeader } from './SettingsSectionHeader';@@ -35,6 +37,7 @@ export function BoundSchemaSection({scopeBadge,slotsAfter,}: BoundSchemaSectionProps) {+ const { t } = useLingui();const { form, commitField } = useConfigForm(binding);const [flashedPath, setFlashedPath] = useState<string | null>(null);const flashTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);@@ -44,7 +47,8 @@ export function BoundSchemaSection({const unsubscribe = subscribeToConfigValidationRejected((event) => {if (event.docName !== docName) return;- toast.error(humanFormat(event.error), { duration: 8000 });+ const held = saveHeldRejection(event.error);+ toast.error(held === null ? humanFormat(event.error) : t(held), { duration: 8000 });const path = firstIssuePath(event.error);if (path) {@@ -65,7 +69,7 @@ export function BoundSchemaSection({unsubscribe();if (flashTimerRef.current) clearTimeout(flashTimerRef.current);};- }, [scope, form]);+ }, [scope, form, t]);return (<Form {...form}>diff --git a/packages/app/src/hooks/use-doc-notices.dom.test.tsx b/packages/app/src/hooks/use-doc-notices.dom.test.tsxindex b84b2de2a..32528f7d9 100644--- a/packages/app/src/hooks/use-doc-notices.dom.test.tsx+++ b/packages/app/src/hooks/use-doc-notices.dom.test.tsx@@ -2,7 +2,7 @@ import type { DocNoticeWire } from '@inkeep/open-knowledge-core/schemas/api';import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { emitBranchChanged, emitDocumentsChanged } from '@/lib/documents-events';-import { DocNoticesProvider, useDocNotice } from './use-doc-notices';+import { DocNoticesProvider, useDocNotices } from './use-doc-notices';function notice(id: string, docName: string): DocNoticeWire {return {@@ -43,14 +43,31 @@ afterEach(() => {cleanup();});+function held(id: string, docName: string): DocNoticeWire {+ return {+ id,+ docName,+ file: `${docName}.md`,+ kind: 'save-held',+ cause: 'keeps-changing',+ firstAt: '2026-10-20T12:00:00.000Z',+ lastAt: '2026-10-20T12:00:00.000Z',+ events: 1,+ entries: [],+ };+}+function Probe({ docName }: { docName: string }) {- const { notice: current, dismiss } = useDocNotice(docName);+ const { notices, dismiss } = useDocNotices(docName);+ const ids = notices.map((shown) => shown.id).join(',');return (<>- <span data-testid={`notice-${docName}`}>{current?.id ?? 'none'}</span>- <button type="button" onClick={() => current && dismiss(current)}>- dismiss {docName}- </button>+ <span data-testid={`notice-${docName}`}>{ids === '' ? 'none' : ids}</span>+ {notices.map((shown) => (+ <button key={shown.id} type="button" onClick={() => dismiss(shown)}>+ dismiss {shown.id}+ </button>+ ))}</>);}@@ -89,13 +106,26 @@ describe('DocNoticesProvider', () => {await waitFor(() => expect(screen.getByTestId('notice-notes').textContent).toBe('none'));});+ test('a document with a held save and a kept version gets both, the held one first', async () => {+ serverNotices = [notice('n-kept', 'notes'), held('n-held', 'notes')];+ renderProbes();++ await waitFor(() =>+ expect(screen.getByTestId('notice-notes').textContent).toBe('n-held,n-kept'),+ );++ fireEvent.click(screen.getByText('dismiss n-held'));++ expect(screen.getByTestId('notice-notes').textContent).toBe('n-kept');+ });+test('a dismissal hides only that document’s notice, and one the server refuses comes back', async () => {serverNotices = [notice('n-notes', 'notes'), notice('n-plan', 'plan')];renderProbes();await waitFor(() => expect(screen.getByTestId('notice-notes').textContent).toBe('n-notes'));dismissStatus = 500;- fireEvent.click(screen.getByText('dismiss notes'));+ fireEvent.click(screen.getByText('dismiss n-notes'));expect(screen.getByTestId('notice-notes').textContent).toBe('none');expect(screen.getByTestId('notice-plan').textContent).toBe('n-plan');diff --git a/packages/app/src/hooks/use-doc-notices.tsx b/packages/app/src/hooks/use-doc-notices.tsxindex 00fd77218..5fdae4aa6 100644--- a/packages/app/src/hooks/use-doc-notices.tsx+++ b/packages/app/src/hooks/use-doc-notices.tsx@@ -58,19 +58,32 @@ export async function dismissDocNotice(docName: string, id: string): Promise<boo}}+type NoticesByDocName = ReadonlyMap<string, readonly DocNoticeWire[]>;+interface DocNoticesContextValue {- byDocName: ReadonlyMap<string, DocNoticeWire>;+ byDocName: NoticesByDocName;dismiss: (notice: DocNoticeWire) => void;}const DocNoticesContext = createContext<DocNoticesContextValue | null>(null);-function indexByDocName(notices: readonly DocNoticeWire[]): ReadonlyMap<string, DocNoticeWire> {- return new Map(notices.map((notice) => [notice.docName, notice]));+const NO_NOTICES: readonly DocNoticeWire[] = [];++function indexByDocName(notices: readonly DocNoticeWire[]): NoticesByDocName {+ const byDocName = new Map<string, DocNoticeWire[]>();+ for (const notice of notices) {+ const forDoc = byDocName.get(notice.docName) ?? [];+ forDoc.push(notice);+ byDocName.set(notice.docName, forDoc);+ }+ for (const forDoc of byDocName.values()) {+ forDoc.sort((a, b) => Number(b.kind === 'save-held') - Number(a.kind === 'save-held'));+ }+ return byDocName;}export function DocNoticesProvider({ children }: { children: ReactNode }) {- const [byDocName, setByDocName] = useState<ReadonlyMap<string, DocNoticeWire>>(() => new Map());+ const [byDocName, setByDocName] = useState<NoticesByDocName>(() => new Map());const latestRequestId = useRef(0);function refresh() {@@ -85,7 +98,11 @@ export function DocNoticesProvider({ children }: { children: ReactNode }) {latestRequestId.current++;setByDocName((previous) => {const next = new Map(previous);- if (next.get(notice.docName)?.id === notice.id) next.delete(notice.docName);+ const remaining = (next.get(notice.docName) ?? NO_NOTICES).filter(+ (shown) => shown.id !== notice.id,+ );+ if (remaining.length === 0) next.delete(notice.docName);+ else next.set(notice.docName, remaining);return next;});void dismissDocNotice(notice.docName, notice.id).then((dismissed) => {@@ -109,11 +126,11 @@ export function DocNoticesProvider({ children }: { children: ReactNode }) {return <DocNoticesContext value={{ byDocName, dismiss }}>{children}</DocNoticesContext>;}-export function useDocNotice(docName: string | null): {- notice: DocNoticeWire | null;+export function useDocNotices(docName: string | null): {+ notices: readonly DocNoticeWire[];dismiss: (notice: DocNoticeWire) => void;} {const value = use(DocNoticesContext);- if (value === null || docName === null) return { notice: null, dismiss: () => {} };- return { notice: value.byDocName.get(docName) ?? null, dismiss: value.dismiss };+ if (value === null || docName === null) return { notices: NO_NOTICES, dismiss: () => {} };+ return { notices: value.byDocName.get(docName) ?? NO_NOTICES, dismiss: value.dismiss };}diff --git a/packages/app/src/lib/save-held-message.ts b/packages/app/src/lib/save-held-message.tsnew file mode 100644index 000000000..f94429ab7--- /dev/null+++ b/packages/app/src/lib/save-held-message.ts@@ -0,0 +1,27 @@+import {+ type ConfigValidationError,+ isKnownConfigError,+} from '@inkeep/open-knowledge-core/config/errors';+import type { DocNoticeWire } from '@inkeep/open-knowledge-core/schemas/api';+import type { MessageDescriptor } from '@lingui/core';+import { msg } from '@lingui/core/macro';++type SaveHeldCause = Extract<DocNoticeWire, { kind: 'save-held' }>['cause'];++export function saveHeldMessage(cause: SaveHeldCause, file: string): MessageDescriptor {+ switch (cause) {+ case 'no-history-or-backup':+ return msg`${file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again.`;+ case 'keeps-changing':+ return msg`${file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again.`;+ case 'not-utf8':+ return msg`${file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes.`;+ case 'unreadable':+ return msg`${file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again.`;+ }+}++export function saveHeldRejection(error: ConfigValidationError): MessageDescriptor | null {+ if (!isKnownConfigError(error) || error.code !== 'SAVE_HELD') return null;+ return saveHeldMessage(error.cause, error.file);+}diff --git a/packages/app/src/locales/ar/messages.po b/packages/app/src/locales/ar/messages.poindex fad45ea78..e758a616d 100644--- a/packages/app/src/locales/ar/messages.po+++ b/packages/app/src/locales/ar/messages.po@@ -585,6 +585,18 @@ msgstr "تعذّر تحديث {failed} من {0} تعليقات."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, zero {فشل رفع {failedCount} ملف} one {فشل رفع ملف واحد} two {فشل رفع ملفين} few {فشل رفع {failedCount} ملفات} many {فشل رفع {failedCount} ملفًا} other {فشل رفع {failedCount} ملف}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "لم يُحفظ {file} لأنه تغيّر خارج OpenKnowledge إلى محتوى ليس نصًا بترميز UTF-8، لذا لم يُكتب فوق الملف. تبقى تعديلاتك هنا، وستُعاد محاولة الحفظ عندما يتغيّر الملف."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "لم يُحفظ {file} لأنه تعذّرت قراءته لمقارنته بالتغييرات الخارجية، لذا لم يُكتب فوق الملف. تبقى تعديلاتك هنا، وستُعاد محاولة الحفظ."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "لم يُحفظ {file} لأنه ظل يتغيّر خارج OpenKnowledge. تبقى تعديلاتك هنا، وستُعاد محاولة الحفظ."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "لم يُحفظ {file}. تغيّر خارج OpenKnowledge، وتعذّر الاحتفاظ بتلك النسخة في السجل أو في مجلد النسخ الاحتياطية، لذا لم يُكتب فوق الملف. تبقى تعديلاتك هنا، وستُعاد محاولة الحفظ."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, zero {# ملف} one {ملف واحد} two {ملفان} few {# ملفات} many {# ملفًا} other {# ملف}}"@@ -1460,9 +1472,18 @@ msgstr "مُدرج دائمًا"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "تعذّر دمج تغيير خارجي في {fileName}، لذا بقيت هذه النسخة. النسخة الخارجية موجودة في الخط الزمني."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "تعذّر دمج تغيير خارجي في {fileName}، لذا بقيت هذه النسخة. حُفظت النسخة الخارجية في {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "تعذّر دمج تغيير خارجي في {fileName}، لذا بقيت هذه النسخة. حُفظت النسخة الخارجية في سجل المستند."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "لم يكن التغيير الخارجي في {fileName} إعدادات صالحة، لذا بقيت إعداداتك. احتُفظ بنسخة من النسخة الخارجية في سجل هذا المشروع، ولا يستطيع التطبيق عرضه بعد."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "لم يكن التغيير الخارجي في {fileName} إعدادات صالحة، لذا بقيت إعداداتك. حُفظت نسخة من النسخة الخارجية في {backupPath}."+msgid "An unexpected error occurred."msgstr "حدث خطأ غير متوقع."@@ -9457,6 +9478,12 @@ msgstr "فشل تحميل الإعدادات"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "إعدادات هذا المشروع. بعضها يُشارك مع كل متعاون عبر git، وبعضها ينطبق على هذا الكمبيوتر فقط."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "تغيّرت الإعدادات في {fileName} خارج OpenKnowledge وأصبحت سارية الآن. احتُفظ بنسخة من التغيير الذي كنت تجريه في سجل هذا المشروع، ولا يستطيع التطبيق عرضه بعد."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "تغيّرت الإعدادات في {fileName} خارج OpenKnowledge وأصبحت سارية الآن. حُفظت نسخة من التغيير الذي كنت تجريه في {backupPath}."+msgid "Settings sections"msgstr "أقسام الإعدادات"diff --git a/packages/app/src/locales/bn/messages.po b/packages/app/src/locales/bn/messages.poindex d769b3b6b..f2358ab38 100644--- a/packages/app/src/locales/bn/messages.po+++ b/packages/app/src/locales/bn/messages.po@@ -585,6 +585,18 @@ msgstr "{0}টির মধ্যে {failed}টি মন্তব্য আপmsgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {১টি ফাইল আপলোড করা যায়নি} other {{failedCount}টি ফাইল আপলোড করা যায়নি}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} সংরক্ষিত হয়নি, কারণ OpenKnowledge-এর বাইরে এটি এমন বিষয়বস্তুতে বদলানো হয়েছে যা UTF-8 টেক্সট নয়, তাই ফাইলটি ওভাররাইট করা হয়নি। আপনার সম্পাদনাগুলো এখানেই রয়েছে, এবং ফাইলটি বদলালে আবার সংরক্ষণের চেষ্টা করা হবে।"++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} সংরক্ষিত হয়নি, কারণ বাইরের পরিবর্তনের সঙ্গে তুলনা করার জন্য এটি পড়া যায়নি, তাই ফাইলটি ওভাররাইট করা হয়নি। আপনার সম্পাদনাগুলো এখানেই রয়েছে, এবং আবার সংরক্ষণের চেষ্টা করা হবে।"++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} সংরক্ষিত হয়নি, কারণ OpenKnowledge-এর বাইরে এটি বারবার বদলাচ্ছিল। আপনার সম্পাদনাগুলো এখানেই রয়েছে, এবং আবার সংরক্ষণের চেষ্টা করা হবে।"++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} সংরক্ষিত হয়নি। OpenKnowledge-এর বাইরে এটি বদলানো হয়েছে, এবং সেই সংস্করণটি ইতিহাসে বা ব্যাকআপ ফোল্ডারে রাখা যায়নি, তাই ফাইলটি ওভাররাইট করা হয়নি। আপনার সম্পাদনাগুলো এখানেই রয়েছে, এবং আবার সংরক্ষণের চেষ্টা করা হবে।"+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# ফাইল} other {# ফাইল}}"@@ -1456,9 +1468,18 @@ msgstr "সবসময় অন্তর্ভুক্ত"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "{fileName}-এ বাইরের একটি পরিবর্তন মার্জ করা যায়নি, তাই এই সংস্করণটি রয়ে গেছে। বাইরের সংস্করণটি কালানুক্রমে আছে।"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "{fileName}-এ বাইরের একটি পরিবর্তন মার্জ করা যায়নি, তাই এই সংস্করণটি রয়ে গেছে। বাইরের সংস্করণটি {backupPath}-এ সংরক্ষিত হয়েছে।"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "{fileName}-এ বাইরের একটি পরিবর্তন মার্জ করা যায়নি, তাই এই সংস্করণটি রয়ে গেছে। বাইরের সংস্করণটি নথির ইতিহাসে সংরক্ষিত হয়েছে।"+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "{fileName}-এ বাইরের পরিবর্তনটি বৈধ সেটিংস ছিল না, তাই আপনার সেটিংস রয়ে গেছে। বাইরের সংস্করণের একটি কপি এই প্রকল্পের ইতিহাসে রাখা হয়েছে, যা অ্যাপ এখনও দেখাতে পারে না।"++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "{fileName}-এ বাইরের পরিবর্তনটি বৈধ সেটিংস ছিল না, তাই আপনার সেটিংস রয়ে গেছে। বাইরের সংস্করণের একটি কপি {backupPath}-এ সংরক্ষিত হয়েছে।"+msgid "An unexpected error occurred."msgstr "একটি অপ্রত্যাশিত ত্রুটি ঘটেছে।"@@ -9453,6 +9474,12 @@ msgstr "সেটিং লোড করা যায়নি"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "এই প্রকল্পের সেটিংস। কিছু git-এর মাধ্যমে প্রতিটি সহযোগীর সঙ্গে ভাগ করা হয়; বাকিগুলি শুধু এই কম্পিউটারে প্রযোজ্য।"+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "{fileName}-এর সেটিংস OpenKnowledge-এর বাইরে বদলানো হয়েছে এবং এখন প্রযোজ্য। আপনি যে পরিবর্তনটি করছিলেন তার একটি কপি এই প্রকল্পের ইতিহাসে রাখা হয়েছে, যা অ্যাপ এখনও দেখাতে পারে না।"++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "{fileName}-এর সেটিংস OpenKnowledge-এর বাইরে বদলানো হয়েছে এবং এখন প্রযোজ্য। আপনি যে পরিবর্তনটি করছিলেন তার একটি কপি {backupPath}-এ সংরক্ষিত হয়েছে।"+msgid "Settings sections"msgstr "সেটিং-এর বিভাগ"diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.poindex 27240b16a..701abbde2 100644--- a/packages/app/src/locales/en/messages.po+++ b/packages/app/src/locales/en/messages.po@@ -585,6 +585,18 @@ msgstr "{failed} of {0} comments could not be updated."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# file} other {# files}}"@@ -1460,9 +1472,18 @@ msgstr "Always included"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgid "An unexpected error occurred."msgstr "An unexpected error occurred."@@ -9457,6 +9478,12 @@ msgstr "Settings failed to load"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgid "Settings sections"msgstr "Settings sections"diff --git a/packages/app/src/locales/es/messages.po b/packages/app/src/locales/es/messages.poindex 0263cb769..d3df2dd50 100644--- a/packages/app/src/locales/es/messages.po+++ b/packages/app/src/locales/es/messages.po@@ -585,6 +585,18 @@ msgstr "No se pudieron actualizar {failed} de {0} comentarios."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {No se pudo subir 1 archivo} many {No se pudieron subir {failedCount} archivos} other {No se pudieron subir {failedCount} archivos}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} no se guardó porque cambió fuera de OpenKnowledge a un contenido que no es texto UTF-8, así que no se sobrescribió el archivo. Tus ediciones se mantienen aquí y se volverá a intentar guardar cuando el archivo cambie."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} no se guardó porque no se pudo leer para compararlo con los cambios externos, así que no se sobrescribió el archivo. Tus ediciones se mantienen aquí y se volverá a intentar guardar."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} no se guardó porque seguía cambiando fuera de OpenKnowledge. Tus ediciones se mantienen aquí y se volverá a intentar guardar."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} no se guardó. Cambió fuera de OpenKnowledge y esa versión no se pudo conservar en el historial ni en la carpeta de copias de seguridad, así que no se sobrescribió el archivo. Tus ediciones se mantienen aquí y se volverá a intentar guardar."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# archivo} many {# archivos} other {# archivos}}"@@ -1460,9 +1472,18 @@ msgstr "Siempre incluido"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "Un cambio externo en {fileName} no se pudo combinar, así que se mantuvo esta versión. La versión externa está en la cronología."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "Un cambio externo en {fileName} no se pudo combinar, así que se mantuvo esta versión. La versión externa se guardó en {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "Un cambio externo en {fileName} no se pudo combinar, así que se mantuvo esta versión. La versión externa se guardó en el historial del documento."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "Un cambio externo en {fileName} no contenía ajustes válidos, así que se mantuvieron tus ajustes. Se guardó una copia de la versión externa en el historial de este proyecto, que la aplicación todavía no puede mostrar."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "Un cambio externo en {fileName} no contenía ajustes válidos, así que se mantuvieron tus ajustes. Se guardó una copia de la versión externa en {backupPath}."+msgid "An unexpected error occurred."msgstr "Se produjo un error inesperado."@@ -9457,6 +9478,12 @@ msgstr "No se pudieron cargar los ajustes"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "Configuración de este proyecto. Una parte se comparte con cada colaborador mediante git; el resto se aplica solo en este equipo."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "Los ajustes de {fileName} cambiaron fuera de OpenKnowledge y ya se aplican. Se guardó una copia del cambio que estabas haciendo en el historial de este proyecto, que la aplicación todavía no puede mostrar."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "Los ajustes de {fileName} cambiaron fuera de OpenKnowledge y ya se aplican. Se guardó una copia del cambio que estabas haciendo en {backupPath}."+msgid "Settings sections"msgstr "Secciones de ajustes"diff --git a/packages/app/src/locales/fr/messages.po b/packages/app/src/locales/fr/messages.poindex e39825289..09cdce09c 100644--- a/packages/app/src/locales/fr/messages.po+++ b/packages/app/src/locales/fr/messages.po@@ -585,6 +585,18 @@ msgstr "{failed} commentaires sur {0} n'ont pas pu être mis à jour."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {L'envoi d'un fichier a échoué} many {L'envoi de {failedCount} fichiers a échoué} other {L'envoi de {failedCount} fichiers a échoué}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} n'a pas été enregistré, car il a été modifié en dehors d'OpenKnowledge avec un contenu qui n'est pas du texte UTF-8, donc le fichier n'a pas été écrasé. Vos modifications restent ici, et l'enregistrement sera retenté quand le fichier changera."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} n'a pas été enregistré, car il n'a pas pu être lu pour le comparer aux modifications externes, donc le fichier n'a pas été écrasé. Vos modifications restent ici, et l'enregistrement sera retenté."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} n'a pas été enregistré, car il continuait de changer en dehors d'OpenKnowledge. Vos modifications restent ici, et l'enregistrement sera retenté."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} n'a pas été enregistré. Il a été modifié en dehors d'OpenKnowledge, et cette version n'a pu être conservée ni dans l'historique ni dans le dossier de sauvegarde, donc le fichier n'a pas été écrasé. Vos modifications restent ici, et l'enregistrement sera retenté."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# fichier} many {# fichiers} other {# fichiers}}"@@ -1460,9 +1472,18 @@ msgstr "Toujours inclus"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "Une modification externe de {fileName} n'a pas pu être fusionnée, donc cette version a été conservée. La version externe se trouve dans la chronologie."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "Une modification externe de {fileName} n'a pas pu être fusionnée, donc cette version a été conservée. La version externe a été enregistrée dans {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "Une modification externe de {fileName} n'a pas pu être fusionnée, donc cette version a été conservée. La version externe a été enregistrée dans l'historique du document."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "Une modification externe de {fileName} ne contenait pas de paramètres valides, donc vos paramètres ont été conservés. Une copie de la version externe a été conservée dans l'historique de ce projet, que l'application ne peut pas encore afficher."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "Une modification externe de {fileName} ne contenait pas de paramètres valides, donc vos paramètres ont été conservés. Une copie de la version externe a été enregistrée dans {backupPath}."+msgid "An unexpected error occurred."msgstr "Une erreur inattendue s'est produite."@@ -9457,6 +9478,12 @@ msgstr "Échec du chargement des paramètres"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "Paramètres de ce projet. Certains sont partagés avec chaque collaborateur via git ; d'autres ne s'appliquent que sur cet ordinateur."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "Les paramètres de {fileName} ont été modifiés en dehors d'OpenKnowledge et s'appliquent désormais. Une copie de la modification que vous étiez en train de faire a été conservée dans l'historique de ce projet, que l'application ne peut pas encore afficher."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "Les paramètres de {fileName} ont été modifiés en dehors d'OpenKnowledge et s'appliquent désormais. Une copie de la modification que vous étiez en train de faire a été enregistrée dans {backupPath}."+msgid "Settings sections"msgstr "Sections des paramètres"diff --git a/packages/app/src/locales/hi/messages.po b/packages/app/src/locales/hi/messages.poindex 586bd2248..e3fb6c6d8 100644--- a/packages/app/src/locales/hi/messages.po+++ b/packages/app/src/locales/hi/messages.po@@ -585,6 +585,18 @@ msgstr "{0} में से {failed} टिप्पणियाँ अपडmsgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {1 फ़ाइल अपलोड नहीं हो सकी} other {{failedCount} फ़ाइलें अपलोड नहीं हो सकीं}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} सहेजी नहीं गई, क्योंकि इसे OpenKnowledge के बाहर ऐसी सामग्री में बदला गया जो UTF-8 टेक्स्ट नहीं है, इसलिए फ़ाइल को ओवरराइट नहीं किया गया। आपके संपादन यहीं बने रहेंगे, और फ़ाइल बदलने पर सहेजने की फिर से कोशिश की जाएगी।"++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} सहेजी नहीं गई, क्योंकि बाहरी बदलावों से तुलना करने के लिए इसे पढ़ा नहीं जा सका, इसलिए फ़ाइल को ओवरराइट नहीं किया गया। आपके संपादन यहीं बने रहेंगे, और सहेजने की फिर से कोशिश की जाएगी।"++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} सहेजी नहीं गई, क्योंकि यह OpenKnowledge के बाहर बार-बार बदलती रही। आपके संपादन यहीं बने रहेंगे, और सहेजने की फिर से कोशिश की जाएगी।"++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} सहेजी नहीं गई। इसे OpenKnowledge के बाहर बदला गया, और वह संस्करण न इतिहास में रखा जा सका न बैकअप फ़ोल्डर में, इसलिए फ़ाइल को ओवरराइट नहीं किया गया। आपके संपादन यहीं बने रहेंगे, और सहेजने की फिर से कोशिश की जाएगी।"+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# फ़ाइल} other {# फ़ाइलें}}"@@ -1456,9 +1468,18 @@ msgstr "हमेशा शामिल"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "{fileName} में बाहर से किया गया बदलाव मर्ज नहीं किया जा सका, इसलिए यह संस्करण बना रहा। बाहरी संस्करण समयरेखा में है।"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "{fileName} में बाहर से किया गया बदलाव मर्ज नहीं किया जा सका, इसलिए यह संस्करण बना रहा। बाहरी संस्करण {backupPath} में सहेजा गया है।"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "{fileName} में बाहर से किया गया बदलाव मर्ज नहीं किया जा सका, इसलिए यह संस्करण बना रहा। बाहरी संस्करण दस्तावेज़ के इतिहास में सहेजा गया है।"+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} में बाहर से किया गया बदलाव मान्य सेटिंग्स नहीं था, इसलिए आपकी सेटिंग्स बनी रहीं। बाहरी संस्करण की एक प्रति इस प्रोजेक्ट के इतिहास में रखी गई है, जिसे ऐप अभी नहीं दिखा सकता।"++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "{fileName} में बाहर से किया गया बदलाव मान्य सेटिंग्स नहीं था, इसलिए आपकी सेटिंग्स बनी रहीं। बाहरी संस्करण की एक प्रति {backupPath} में सहेजी गई है।"+msgid "An unexpected error occurred."msgstr "एक अप्रत्याशित त्रुटि हुई।"@@ -9453,6 +9474,12 @@ msgstr "सेटिंग लोड नहीं हो सकीं"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "इस प्रोजेक्ट की सेटिंग्स। कुछ git के ज़रिए हर सहयोगी के साथ साझा होती हैं; बाक़ी केवल इस कंप्यूटर पर लागू होती हैं।"+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} की सेटिंग्स OpenKnowledge के बाहर बदली गईं और अब लागू हैं। आप जो बदलाव कर रहे थे, उसकी एक प्रति इस प्रोजेक्ट के इतिहास में रखी गई है, जिसे ऐप अभी नहीं दिखा सकता।"++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "{fileName} की सेटिंग्स OpenKnowledge के बाहर बदली गईं और अब लागू हैं। आप जो बदलाव कर रहे थे, उसकी एक प्रति {backupPath} में सहेजी गई है।"+msgid "Settings sections"msgstr "सेटिंग अनुभाग"diff --git a/packages/app/src/locales/id/messages.po b/packages/app/src/locales/id/messages.poindex e76797266..3ee611c45 100644--- a/packages/app/src/locales/id/messages.po+++ b/packages/app/src/locales/id/messages.po@@ -585,6 +585,18 @@ msgstr "{failed} dari {0} komentar tidak dapat diperbarui."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, other {{failedCount} berkas gagal diunggah}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} tidak disimpan karena diubah dari luar OpenKnowledge menjadi konten yang bukan teks UTF-8, jadi file tidak ditimpa. Suntingan Anda tetap di sini, dan penyimpanan akan dicoba lagi saat file berubah."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} tidak disimpan karena tidak bisa dibaca untuk dibandingkan dengan perubahan dari luar, jadi file tidak ditimpa. Suntingan Anda tetap di sini, dan penyimpanan akan dicoba lagi."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} tidak disimpan karena terus berubah dari luar OpenKnowledge. Suntingan Anda tetap di sini, dan penyimpanan akan dicoba lagi."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} tidak disimpan. File ini diubah dari luar OpenKnowledge, dan versi tersebut tidak bisa disimpan di riwayat maupun di folder cadangan, jadi file tidak ditimpa. Suntingan Anda tetap di sini, dan penyimpanan akan dicoba lagi."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, other {# berkas}}"@@ -1456,9 +1468,18 @@ msgstr "Selalu disertakan"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "Perubahan dari luar pada {fileName} tidak bisa digabungkan, jadi versi ini tetap dipakai. Versi dari luar ada di lini masa."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "Perubahan dari luar pada {fileName} tidak bisa digabungkan, jadi versi ini tetap dipakai. Versi dari luar disimpan di {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "Perubahan dari luar pada {fileName} tidak bisa digabungkan, jadi versi ini tetap dipakai. Versi dari luar disimpan di riwayat dokumen."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "Perubahan dari luar pada {fileName} bukan pengaturan yang valid, jadi pengaturan Anda tetap dipakai. Salinan versi dari luar disimpan di riwayat proyek ini, yang belum bisa ditampilkan aplikasi."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "Perubahan dari luar pada {fileName} bukan pengaturan yang valid, jadi pengaturan Anda tetap dipakai. Salinan versi dari luar disimpan di {backupPath}."+msgid "An unexpected error occurred."msgstr "Terjadi galat yang tidak terduga."@@ -9453,6 +9474,12 @@ msgstr "Gagal memuat pengaturan"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "Pengaturan untuk proyek ini. Sebagian dibagikan ke setiap kolaborator lewat git; sisanya hanya berlaku di komputer ini."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "Pengaturan di {fileName} diubah dari luar OpenKnowledge dan kini berlaku. Salinan perubahan yang sedang Anda buat disimpan di riwayat proyek ini, yang belum bisa ditampilkan aplikasi."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "Pengaturan di {fileName} diubah dari luar OpenKnowledge dan kini berlaku. Salinan perubahan yang sedang Anda buat disimpan di {backupPath}."+msgid "Settings sections"msgstr "Bagian pengaturan"diff --git a/packages/app/src/locales/ko/messages.po b/packages/app/src/locales/ko/messages.poindex 922079f86..97a43a5ab 100644--- a/packages/app/src/locales/ko/messages.po+++ b/packages/app/src/locales/ko/messages.po@@ -585,6 +585,18 @@ msgstr "댓글 {0}개 중 {failed}개 업데이트에 실패했습니다."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, other {{failedCount}개 파일을 업로드하지 못했습니다}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file}이(가) OpenKnowledge 밖에서 UTF-8 텍스트가 아닌 내용으로 변경되어 저장되지 않았고, 파일을 덮어쓰지 않았습니다. 편집 내용은 여기에 그대로 있으며, 파일이 변경되면 다시 저장을 시도합니다."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file}을(를) 외부 변경과 비교하기 위해 읽을 수 없어 저장되지 않았고, 파일을 덮어쓰지 않았습니다. 편집 내용은 여기에 그대로 있으며, 다시 저장을 시도합니다."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file}이(가) OpenKnowledge 밖에서 계속 변경되어 저장되지 않았습니다. 편집 내용은 여기에 그대로 있으며, 다시 저장을 시도합니다."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file}이(가) 저장되지 않았습니다. OpenKnowledge 밖에서 변경되었지만 그 버전을 기록이나 백업 폴더에 보관할 수 없어 파일을 덮어쓰지 않았습니다. 편집 내용은 여기에 그대로 있으며, 다시 저장을 시도합니다."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, other {파일 #개}}"@@ -1460,9 +1472,18 @@ msgstr "항상 포함"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "{fileName}의 외부 변경을 병합할 수 없어 이 버전이 유지되었습니다. 외부 버전은 타임라인에 있습니다."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "{fileName}의 외부 변경을 병합할 수 없어 이 버전이 유지되었습니다. 외부 버전은 {backupPath}에 저장되었습니다."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "{fileName}의 외부 변경을 병합할 수 없어 이 버전이 유지되었습니다. 외부 버전은 문서 기록에 저장되었습니다."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "{fileName}의 외부 변경이 올바른 설정이 아니어서 기존 설정이 유지되었습니다. 외부 버전의 사본은 이 프로젝트 기록에 보관되었지만, 앱에서는 아직 볼 수 없습니다."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "{fileName}의 외부 변경이 올바른 설정이 아니어서 기존 설정이 유지되었습니다. 외부 버전의 사본은 {backupPath}에 저장되었습니다."+msgid "An unexpected error occurred."msgstr "예기치 않은 오류가 발생했습니다."@@ -9457,6 +9478,12 @@ msgstr "설정을 불러오지 못했습니다"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "이 프로젝트의 설정입니다. 일부는 git을 통해 모든 협업자와 공유되고, 일부는 이 컴퓨터에만 적용됩니다."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "{fileName}의 설정이 OpenKnowledge 밖에서 변경되어 이제 적용됩니다. 진행 중이던 변경 내용의 사본은 이 프로젝트 기록에 보관되었지만, 앱에서는 아직 볼 수 없습니다."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "{fileName}의 설정이 OpenKnowledge 밖에서 변경되어 이제 적용됩니다. 진행 중이던 변경 내용의 사본은 {backupPath}에 저장되었습니다."+msgid "Settings sections"msgstr "설정 섹션"diff --git a/packages/app/src/locales/pl/messages.po b/packages/app/src/locales/pl/messages.poindex e4d6fb22c..629c8d721 100644--- a/packages/app/src/locales/pl/messages.po+++ b/packages/app/src/locales/pl/messages.po@@ -585,6 +585,18 @@ msgstr "Nie udało się zaktualizować {failed} z {0} komentarzy."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {Nie udało się wgrać 1 pliku} few {Nie udało się wgrać {failedCount} plików} many {Nie udało się wgrać {failedCount} plików} other {Nie udało się wgrać {failedCount} pliku}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "Nie zapisano {file}, ponieważ plik zmieniono poza OpenKnowledge na treść, która nie jest tekstem UTF-8, więc nie został nadpisany. Twoje edycje pozostają tutaj, a zapis zostanie ponowiony, gdy plik się zmieni."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "Nie zapisano {file}, ponieważ nie udało się go odczytać, aby porównać go ze zmianami zewnętrznymi, więc plik nie został nadpisany. Twoje edycje pozostają tutaj, a zapis zostanie ponowiony."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "Nie zapisano {file}, ponieważ plik ciągle zmieniał się poza OpenKnowledge. Twoje edycje pozostają tutaj, a zapis zostanie ponowiony."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "Nie zapisano {file}. Plik zmieniono poza OpenKnowledge, a tej wersji nie udało się zachować ani w historii, ani w folderze kopii zapasowych, więc plik nie został nadpisany. Twoje edycje pozostają tutaj, a zapis zostanie ponowiony."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}"@@ -1460,9 +1472,18 @@ msgstr "Zawsze dołączane"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "Zewnętrznej zmiany w {fileName} nie udało się scalić, więc ta wersja została zachowana. Wersja zewnętrzna jest na osi czasu."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "Zewnętrznej zmiany w {fileName} nie udało się scalić, więc ta wersja została zachowana. Wersję zewnętrzną zapisano w {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "Zewnętrznej zmiany w {fileName} nie udało się scalić, więc ta wersja została zachowana. Wersję zewnętrzną zapisano w historii dokumentu."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "Zewnętrzna zmiana w {fileName} nie zawierała prawidłowych ustawień, więc Twoje ustawienia zostały zachowane. Kopię wersji zewnętrznej zachowano w historii tego projektu, której aplikacja nie potrafi jeszcze pokazać."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "Zewnętrzna zmiana w {fileName} nie zawierała prawidłowych ustawień, więc Twoje ustawienia zostały zachowane. Kopię wersji zewnętrznej zapisano w {backupPath}."+msgid "An unexpected error occurred."msgstr "Wystąpił nieoczekiwany błąd."@@ -9457,6 +9478,12 @@ msgstr "Nie udało się wczytać ustawień"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "Ustawienia tego projektu. Część jest współdzielona ze wszystkimi współpracownikami przez Gita; inne dotyczą tylko tego komputera."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "Ustawienia w {fileName} zmieniono poza OpenKnowledge i teraz obowiązują. Kopię wprowadzanej przez Ciebie zmiany zachowano w historii tego projektu, której aplikacja nie potrafi jeszcze pokazać."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "Ustawienia w {fileName} zmieniono poza OpenKnowledge i teraz obowiązują. Kopię wprowadzanej przez Ciebie zmiany zapisano w {backupPath}."+msgid "Settings sections"msgstr "Sekcje ustawień"diff --git a/packages/app/src/locales/pt-BR/messages.po b/packages/app/src/locales/pt-BR/messages.poindex 168b9059b..63c0f56db 100644--- a/packages/app/src/locales/pt-BR/messages.po+++ b/packages/app/src/locales/pt-BR/messages.po@@ -585,6 +585,18 @@ msgstr "Não foi possível atualizar {failed} de {0} comentários."msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {Falha ao enviar 1 arquivo} many {Falha ao enviar {failedCount} arquivos} other {Falha ao enviar {failedCount} arquivos}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} não foi salvo porque foi alterado fora do OpenKnowledge para um conteúdo que não é texto UTF-8, então o arquivo não foi sobrescrito. Suas edições continuam aqui, e o salvamento será tentado de novo quando o arquivo mudar."++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} não foi salvo porque não pôde ser lido para compará-lo com alterações externas, então o arquivo não foi sobrescrito. Suas edições continuam aqui, e o salvamento será tentado de novo."++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} não foi salvo porque continuava mudando fora do OpenKnowledge. Suas edições continuam aqui, e o salvamento será tentado de novo."++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} não foi salvo. Ele foi alterado fora do OpenKnowledge, e essa versão não pôde ser guardada no histórico nem na pasta de backup, então o arquivo não foi sobrescrito. Suas edições continuam aqui, e o salvamento será tentado de novo."+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# arquivo} many {# arquivos} other {# arquivos}}"@@ -1456,9 +1468,18 @@ msgstr "Sempre incluído"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "Uma alteração externa em {fileName} não pôde ser mesclada, então esta versão foi mantida. A versão externa está na linha do tempo."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "Uma alteração externa em {fileName} não pôde ser mesclada, então esta versão foi mantida. A versão externa foi salva em {backupPath}."+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "Uma alteração externa em {fileName} não pôde ser mesclada, então esta versão foi mantida. A versão externa foi salva no histórico do documento."+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "Uma alteração externa em {fileName} não continha configurações válidas, então suas configurações foram mantidas. Uma cópia da versão externa foi guardada no histórico deste projeto, que o aplicativo ainda não consegue mostrar."++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "Uma alteração externa em {fileName} não continha configurações válidas, então suas configurações foram mantidas. Uma cópia da versão externa foi salva em {backupPath}."+msgid "An unexpected error occurred."msgstr "Ocorreu um erro inesperado."@@ -9453,6 +9474,12 @@ msgstr "Falha ao carregar as configurações"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "Configurações deste projeto. Algumas são compartilhadas com cada colaborador pelo git; outras se aplicam somente neste computador."+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "As configurações em {fileName} foram alteradas fora do OpenKnowledge e agora estão em vigor. Uma cópia da alteração que você estava fazendo foi guardada no histórico deste projeto, que o aplicativo ainda não consegue mostrar."++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "As configurações em {fileName} foram alteradas fora do OpenKnowledge e agora estão em vigor. Uma cópia da alteração que você estava fazendo foi salva em {backupPath}."+msgid "Settings sections"msgstr "Seções das configurações"diff --git a/packages/app/src/locales/ur/messages.po b/packages/app/src/locales/ur/messages.poindex 6ab667672..42788b0f7 100644--- a/packages/app/src/locales/ur/messages.po+++ b/packages/app/src/locales/ur/messages.po@@ -585,6 +585,18 @@ msgstr "{0} میں سے {failed} تبصرے اپ ڈیٹ نہیں ہو سکے۔"msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, one {1 فائل اپ لوڈ نہیں ہو سکی} other {{failedCount} فائلیں اپ لوڈ نہیں ہو سکیں}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} محفوظ نہیں ہوئی، کیونکہ اسے OpenKnowledge کے باہر ایسے مواد میں بدلا گیا جو UTF-8 متن نہیں ہے، اس لیے فائل کو اوور رائٹ نہیں کیا گیا۔ آپ کی ترامیم یہیں موجود ہیں، اور فائل بدلنے پر محفوظ کرنے کی دوبارہ کوشش کی جائے گی۔"++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} محفوظ نہیں ہوئی، کیونکہ باہر کی تبدیلیوں سے موازنہ کرنے کے لیے اسے پڑھا نہیں جا سکا، اس لیے فائل کو اوور رائٹ نہیں کیا گیا۔ آپ کی ترامیم یہیں موجود ہیں، اور محفوظ کرنے کی دوبارہ کوشش کی جائے گی۔"++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} محفوظ نہیں ہوئی، کیونکہ یہ OpenKnowledge کے باہر بار بار بدلتی رہی۔ آپ کی ترامیم یہیں موجود ہیں، اور محفوظ کرنے کی دوبارہ کوشش کی جائے گی۔"++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} محفوظ نہیں ہوئی۔ اسے OpenKnowledge کے باہر بدلا گیا، اور وہ ورژن نہ تاریخ میں رکھا جا سکا نہ بیک اپ فولڈر میں، اس لیے فائل کو اوور رائٹ نہیں کیا گیا۔ آپ کی ترامیم یہیں موجود ہیں، اور محفوظ کرنے کی دوبارہ کوشش کی جائے گی۔"+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, one {# فائل} other {# فائلیں}}"@@ -1460,9 +1472,18 @@ msgstr "ہمیشہ شامل"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "{fileName} میں باہر سے کی گئی تبدیلی مرج نہیں ہو سکی، اس لیے یہی ورژن رہا۔ باہر والا ورژن ٹائم لائن میں ہے۔"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "{fileName} میں باہر سے کی گئی تبدیلی مرج نہیں ہو سکی، اس لیے یہی ورژن رہا۔ باہر والا ورژن {backupPath} میں محفوظ کر دیا گیا ہے۔"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "{fileName} میں باہر سے کی گئی تبدیلی مرج نہیں ہو سکی، اس لیے یہی ورژن رہا۔ باہر والا ورژن دستاویز کی تاریخ میں محفوظ کر دیا گیا ہے۔"+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} میں باہر سے کی گئی تبدیلی درست ترتیبات نہیں تھی، اس لیے آپ کی ترتیبات برقرار رہیں۔ باہر والے ورژن کی ایک نقل اس پروجیکٹ کی تاریخ میں رکھی گئی ہے، جسے ایپ ابھی نہیں دکھا سکتی۔"++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "{fileName} میں باہر سے کی گئی تبدیلی درست ترتیبات نہیں تھی، اس لیے آپ کی ترتیبات برقرار رہیں۔ باہر والے ورژن کی ایک نقل {backupPath} میں محفوظ کی گئی ہے۔"+msgid "An unexpected error occurred."msgstr "ایک غیر متوقع خرابی پیش آئی۔"@@ -9457,6 +9478,12 @@ msgstr "ترتیبات لوڈ نہیں ہو سکیں"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "اس پروجیکٹ کی ترتیبات۔ کچھ git کے ذریعے ہر ساتھی کے ساتھ مشترک ہوتی ہیں؛ باقی صرف اسی کمپیوٹر پر لاگو ہوتی ہیں۔"+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} کی ترتیبات OpenKnowledge کے باہر بدلی گئیں اور اب لاگو ہیں۔ آپ جو تبدیلی کر رہے تھے اس کی ایک نقل اس پروجیکٹ کی تاریخ میں رکھی گئی ہے، جسے ایپ ابھی نہیں دکھا سکتی۔"++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "{fileName} کی ترتیبات OpenKnowledge کے باہر بدلی گئیں اور اب لاگو ہیں۔ آپ جو تبدیلی کر رہے تھے اس کی ایک نقل {backupPath} میں محفوظ کی گئی ہے۔"+msgid "Settings sections"msgstr "ترتیبات کے سیکشنز"diff --git a/packages/app/src/locales/zh-Hans/messages.po b/packages/app/src/locales/zh-Hans/messages.poindex d6fd20d6e..1c2a55ff5 100644--- a/packages/app/src/locales/zh-Hans/messages.po+++ b/packages/app/src/locales/zh-Hans/messages.po@@ -585,6 +585,18 @@ msgstr "{0} 条评论中有 {failed} 条无法更新。"msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, other {{failedCount} 个文件上传失败}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} 未保存,因为它在 OpenKnowledge 之外被改成了非 UTF-8 文本的内容,所以没有覆盖该文件。你的编辑仍保留在这里,文件再次更改时会重新尝试保存。"++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} 未保存,因为无法读取它来与外部更改进行比较,所以没有覆盖该文件。你的编辑仍保留在这里,稍后会重新尝试保存。"++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} 未保存,因为它在 OpenKnowledge 之外不断更改。你的编辑仍保留在这里,稍后会重新尝试保存。"++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} 未保存。它在 OpenKnowledge 之外被更改,而该版本无法保存到历史记录或备份文件夹中,所以没有覆盖该文件。你的编辑仍保留在这里,稍后会重新尝试保存。"+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, other {# 个文件}}"@@ -1460,9 +1472,18 @@ msgstr "始终包含"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "{fileName} 的外部更改无法合并,因此保留了当前版本。外部版本在时间线中。"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "{fileName} 的外部更改无法合并,因此保留了当前版本。外部版本已保存到 {backupPath}。"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "{fileName} 的外部更改无法合并,因此保留了当前版本。外部版本已保存到文档的历史记录中。"+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} 的外部更改不是有效的设置,因此保留了你的设置。外部版本已保存一份副本到本项目的历史记录中,应用暂时无法显示这些记录。"++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "{fileName} 的外部更改不是有效的设置,因此保留了你的设置。外部版本已保存一份副本到 {backupPath}。"+msgid "An unexpected error occurred."msgstr "发生了意外错误。"@@ -9457,6 +9478,12 @@ msgstr "设置加载失败"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "本项目的设置。部分设置通过 git 与每位协作者共享;其余仅在这台电脑上生效。"+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} 中的设置已在 OpenKnowledge 之外更改,现已生效。你正在进行的更改已保存一份副本到本项目的历史记录中,应用暂时无法显示这些记录。"++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "{fileName} 中的设置已在 OpenKnowledge 之外更改,现已生效。你正在进行的更改已保存一份副本到 {backupPath}。"+msgid "Settings sections"msgstr "设置分区"diff --git a/packages/app/src/locales/zh-Hant/messages.po b/packages/app/src/locales/zh-Hant/messages.poindex a61f43bc8..143c45876 100644--- a/packages/app/src/locales/zh-Hant/messages.po+++ b/packages/app/src/locales/zh-Hant/messages.po@@ -585,6 +585,18 @@ msgstr "{0} 則註解中有 {failed} 則無法更新。"msgid "{failedCount, plural, one {1 file failed to upload} other {{failedCount} files failed to upload}}"msgstr "{failedCount, plural, other {{failedCount} 個檔案上傳失敗}}"+msgid "{file} was not saved because it changed outside OpenKnowledge to content that is not UTF-8 text, so the file was not written over. Your edits stay here, and saving is tried again when the file changes."+msgstr "{file} 未儲存,因為它在 OpenKnowledge 之外被改成了非 UTF-8 文字的內容,所以沒有覆寫該檔案。你的編輯仍保留在這裡,檔案再次變更時會重新嘗試儲存。"++msgid "{file} was not saved because it could not be read to compare it with outside changes, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} 未儲存,因為無法讀取它來與外部變更進行比較,所以沒有覆寫該檔案。你的編輯仍保留在這裡,稍後會重新嘗試儲存。"++msgid "{file} was not saved because it kept changing outside OpenKnowledge. Your edits stay here, and saving is tried again."+msgstr "{file} 未儲存,因為它在 OpenKnowledge 之外持續變更。你的編輯仍保留在這裡,稍後會重新嘗試儲存。"++msgid "{file} was not saved. It changed outside OpenKnowledge, and that version could not be kept in history or in the backup folder, so the file was not written over. Your edits stay here, and saving is tried again."+msgstr "{file} 未儲存。它在 OpenKnowledge 之外被變更,而該版本無法儲存到記錄或備份資料夾中,所以沒有覆寫該檔案。你的編輯仍保留在這裡,稍後會重新嘗試儲存。"+msgid "{fileCount, plural, one {# file} other {# files}}"msgstr "{fileCount, plural, other {# 個檔案}}"@@ -1460,9 +1472,18 @@ msgstr "一律包含"msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version is in the timeline."msgstr "{fileName} 的外部變更無法合併,因此保留了目前的版本。外部版本在時間軸中。"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to {backupPath}."+msgstr "{fileName} 的外部變更無法合併,因此保留了目前的版本。外部版本已儲存到 {backupPath}。"+msgid "An outside change to {fileName} could not be merged, so this version stayed. The outside version was saved to the document's history."msgstr "{fileName} 的外部變更無法合併,因此保留了目前的版本。外部版本已儲存到文件的記錄中。"+msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} 的外部變更不是有效的設定,因此保留了你的設定。外部版本已儲存一份副本到這個專案的記錄中,應用程式暫時無法顯示這些記錄。"++msgid "An outside change to {fileName} was not valid settings, so your settings stayed. A copy of the outside version was saved to {backupPath}."+msgstr "{fileName} 的外部變更不是有效的設定,因此保留了你的設定。外部版本已儲存一份副本到 {backupPath}。"+msgid "An unexpected error occurred."msgstr "發生了非預期的錯誤。"@@ -9457,6 +9478,12 @@ msgstr "設定載入失敗"msgid "Settings for this project. Some are shared with every collaborator through git; others apply only on this computer."msgstr "這個專案的設定。部分設定會透過 git 與每位協作者分享;其餘只在這台電腦上生效。"+msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was kept in this project's history, which the app cannot show yet."+msgstr "{fileName} 中的設定已在 OpenKnowledge 之外變更,現已生效。你正在進行的變更已儲存一份副本到這個專案的記錄中,應用程式暫時無法顯示這些記錄。"++msgid "Settings in {fileName} changed outside OpenKnowledge and now apply. A copy of the change you were making was saved to {backupPath}."+msgstr "{fileName} 中的設定已在 OpenKnowledge 之外變更,現已生效。你正在進行的變更已儲存一份副本到 {backupPath}。"+msgid "Settings sections"msgstr "設定分區"diff --git a/packages/app/tests/integration/engineless-outside-change.test.ts b/packages/app/tests/integration/engineless-outside-change.test.tsnew file mode 100644index 000000000..473e85ad8--- /dev/null+++ b/packages/app/tests/integration/engineless-outside-change.test.ts@@ -0,0 +1,536 @@+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ realpathSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import { afterEach, describe, expect, test } from 'vitest';+import * as Y from 'yjs';+import { getMetrics } from '../../../server/src/metrics';+import { saveInMemoryCheckpoint } from '../../../server/src/shadow-repo';+import { createManualClock, type ManualClock } from '../../../server/src/watcher-clock.test-helper';+import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';+import {+ createTestClient,+ createTestServer,+ pollUntil,+ type TestClient,+ type TestServer,+} from './test-harness';++let server: TestServer | undefined;+let client: TestClient | undefined;+const homes: string[] = [];++afterEach(async () => {+ await client?.cleanup();+ client = undefined;+ await server?.cleanup();+ server = undefined;+ for (const home of homes.splice(0)) rmSync(home, { recursive: true, force: true });+});++function ownHome(): string {+ const home = realpathSync(mkdtempSync(join(tmpdir(), 'ok-engineless-home-')));+ homes.push(home);+ return home;+}++function backupsIn(home: string): string[] {+ const root = join(home, '.ok', 'edit-backups', 'discarded');+ if (!existsSync(root)) return [];+ return readdirSync(root, { recursive: true, withFileTypes: true })+ .filter((entry) => entry.isFile())+ .map((entry) => readFileSync(join(entry.parentPath, entry.name), 'utf-8'));+}++function blockBackups(home: string): void {+ mkdirSync(join(home, '.ok'), { recursive: true });+ writeFileSync(join(home, '.ok', 'edit-backups'), 'not a folder');+}++function unblockBackups(home: string): void {+ rmSync(join(home, '.ok', 'edit-backups'), { force: true });+}++interface Rig {+ s: TestServer;+ c: TestClient;+ double: ReturnType<typeof createWatcherDouble>;+ clock: ManualClock;+ path: string;+}++interface HistoryVersion {+ kind: string | undefined;+ side: unknown;+ fileType: unknown;+ content: string;+}++const CASES = [+ {+ file: 'diagrams/flow.mmd',+ fileType: 'mermaid',+ saved: 'graph TD\n A-->B\n',+ edit: { find: 'A-->B', replace: 'A-->C' },+ outside: 'graph TD\n A-->D\n',+ },+ {+ file: 'boards/plan.excalidraw',+ fileType: 'excalidraw',+ saved: '{"type":"excalidraw","version":2,"elements":[{"id":"a","type":"rectangle","x":0}]}\n',+ edit: { find: '"x":0', replace: '"x":10' },+ outside:+ '{"type":"excalidraw","version":2,"elements":[{"id":"a","type":"rectangle","x":20}]}\n',+ },+ {+ file: 'notes/todo.txt',+ fileType: 'text',+ saved: 'first line\nsecond line\n',+ edit: { find: 'second line', replace: 'second line, edited here' },+ outside: 'first line\nsecond line, edited outside\n',+ },+] as const;++function liveText(s: TestServer, docName: string): string | null {+ return s.instance.hocuspocus.documents.get(docName)?.getText('source').toString() ?? null;+}++async function openSaved(+ file: string,+ saved: string,+ options: {+ freshnessIntervalMs?: number | null;+ historyFails?: () => boolean;+ stalenessSweepIntervalMs?: number;+ keepContentDir?: boolean;+ home?: string;+ } = {},+): Promise<Rig> {+ const double = createWatcherDouble();+ const clock = createManualClock(Date.now());+ const historyFails = options.historyFails;+ const s = await createTestServer({+ gitEnabled: true,+ watcherBackend: double.backend,+ watcherClock: clock,+ freshnessIntervalMs: options.freshnessIntervalMs ?? null,+ debounce: 300_000,+ maxDebounce: 600_000,+ stalenessSweepIntervalMs: options.stalenessSweepIntervalMs,+ keepContentDir: options.keepContentDir,+ configHomedirOverride: options.home,+ mergeHistoryWriter:+ historyFails === undefined+ ? undefined+ : (shadow, contentRoot, params) =>+ historyFails()+ ? Promise.reject(new Error('history is unavailable'))+ : saveInMemoryCheckpoint(shadow, contentRoot, params),+ });+ server = s;+ const path = join(s.contentDir, file);+ mkdirSync(join(path, '..'), { recursive: true });+ writeFileSync(path, saved, 'utf-8');+ const c = await createTestClient(s.port, file, {+ skipInvariantWatcher: true,+ resetOnCleanup: false,+ });+ client = c;+ await pollUntil(() => c.ytext.toString() === saved, 10_000, 25, `${file} to load`);+ return { s, c, double, clock, path };+}++function editInClient(c: TestClient, find: string, replace: string): void {+ c.doc.transact(() => {+ const at = c.ytext.toString().indexOf(find);+ c.ytext.delete(at, find.length);+ c.ytext.insert(at, replace);+ });+}++async function flushPendingStore(s: TestServer, docName: string): Promise<void> {+ const id = `onStoreDocument-${docName}`;+ if (s.instance.hocuspocus.debouncer.isDebounced(id)) {+ await s.instance.hocuspocus.debouncer.executeNow(id);+ }+}++async function historyVersions(s: TestServer, docName: string): Promise<HistoryVersion[]> {+ const res = await fetch(+ `${s.baseUrl}/api/history?docName=${encodeURIComponent(docName)}&type=checkpoint&limit=100`,+ );+ const body = (await res.json()) as {+ entries?: Array<{+ sha: string;+ checkpoint?: { kind?: string; metadata?: { side?: unknown; fileType?: unknown } };+ }>;+ };+ const versions: HistoryVersion[] = [];+ for (const row of body.entries ?? []) {+ const content = await fetch(+ `${s.baseUrl}/api/history/${row.sha}?docName=${encodeURIComponent(docName)}`,+ ).then((r) => r.json() as Promise<{ content: string }>);+ versions.push({+ kind: row.checkpoint?.kind,+ side: row.checkpoint?.metadata?.side,+ fileType: row.checkpoint?.metadata?.fileType,+ content: content.content,+ });+ }+ return versions;+}++async function noticesFor(s: TestServer, docName: string): Promise<Array<Record<string, unknown>>> {+ const res = await fetch(`${s.baseUrl}/api/doc-notices`);+ const body = (await res.json()) as { notices?: Array<Record<string, unknown>> };+ return (body.notices ?? []).filter((notice) => notice.docName === docName);+}++describe('an outside write to a file with no merge engine, under unsaved edits', () => {+ for (const kase of CASES) {+ test(`${kase.file}: the save keeps the edits live and on disk and moves the outside version to history`, async () => {+ const { s, c, path } = await openSaved(kase.file, kase.saved);+ const undo = new Y.UndoManager(c.ytext);+ editInClient(c, kase.edit.find, kase.edit.replace);+ const here = kase.saved.replace(kase.edit.find, kase.edit.replace);+ await pollUntil(+ () => liveText(s, kase.file) === here,+ 10_000,+ 25,+ 'the edit to reach the server',+ );+ writeFileSync(path, kase.outside, 'utf-8');++ await flushPendingStore(s, kase.file);++ await pollUntil(+ () => readFileSync(path, 'utf-8') === here,+ 10_000,+ 25,+ 'the save to write the edits',+ );+ expect(liveText(s, kase.file)).toBe(here);+ expect(c.ytext.toString()).toBe(here);+ expect(undo.undoStack).toHaveLength(1);+ expect(await historyVersions(s, kase.file)).toEqual([+ {+ kind: 'external-change-no-engine',+ side: 'theirs',+ fileType: kase.fileType,+ content: kase.outside,+ },+ ]);+ const notices = await noticesFor(s, kase.file);+ expect(notices).toEqual([+ expect.objectContaining({+ kind: 'moved-to-history',+ side: 'theirs',+ reason: 'no-merge-engine',+ file: kase.file,+ }),+ ]);+ undo.undo();+ await pollUntil(() => liveText(s, kase.file) === kase.saved, 10_000, 25, 'the undo to land');+ });+ }+});++describe('an outside version that history cannot take', () => {+ const kase = CASES[0];+ const here = kase.saved.replace(kase.edit.find, kase.edit.replace);++ async function saveOverOutsideWrite(rig: Rig, outside: string | Buffer = kase.outside) {+ editInClient(rig.c, kase.edit.find, kase.edit.replace);+ await pollUntil(() => liveText(rig.s, kase.file) === here, 10_000, 25, 'the edit');+ writeFileSync(rig.path, outside);+ await flushPendingStore(rig.s, kase.file);+ }++ test('goes to the backup folder, the edits are written, and the notice names the backup', async () => {+ const home = ownHome();+ const rig = await openSaved(kase.file, kase.saved, { historyFails: () => true, home });++ await saveOverOutsideWrite(rig);++ await pollUntil(+ () => readFileSync(rig.path, 'utf-8') === here,+ 10_000,+ 25,+ 'the save to write the edits',+ );+ expect(backupsIn(home)).toEqual([kase.outside]);+ expect(await historyVersions(rig.s, kase.file)).toEqual([]);+ expect(await noticesFor(rig.s, kase.file)).toEqual([+ expect.objectContaining({+ kind: 'moved-to-backup',+ side: 'theirs',+ reason: 'no-merge-engine',+ backup: expect.stringMatching(+ /^~\/\.ok\/edit-backups\/discarded\/projects\/[0-9a-f]{8}\/diagrams__flow\.mmd\/.+\.mmd$/,+ ),+ }),+ ]);+ });++ test('with no backup folder either, the save is held with a notice and the edits are in the rescue buffer at shutdown', async () => {+ const home = ownHome();+ blockBackups(home);+ const rig = await openSaved(kase.file, kase.saved, {+ historyFails: () => true,+ keepContentDir: true,+ home,+ });+ const contentDir = rig.s.contentDir;+ const rescued = join(resolveShadowDir(contentDir), 'rescue', kase.file);+ try {+ await saveOverOutsideWrite(rig);+ await pollUntil(+ async () => (await noticesFor(rig.s, kase.file)).length > 0,+ 10_000,+ 25,+ 'the held-save notice',+ );+ expect(await noticesFor(rig.s, kase.file)).toEqual([+ expect.objectContaining({ kind: 'save-held', cause: 'no-history-or-backup' }),+ ]);+ expect(readFileSync(rig.path, 'utf-8')).toBe(kase.outside);++ await client?.cleanup();+ client = undefined;+ await server?.cleanup();+ server = undefined;++ expect(existsSync(rescued)).toBe(true);+ expect(readFileSync(rescued, 'utf-8')).toBe(here);+ expect(readFileSync(rig.path, 'utf-8')).toBe(kase.outside);+ } finally {+ rmSync(contentDir, { recursive: true, force: true });+ }+ });++ test('a held save is retried and lands once history can take the outside version, replacing the held notice', async () => {+ const home = ownHome();+ blockBackups(home);+ let failing = true;+ const rig = await openSaved(kase.file, kase.saved, {+ historyFails: () => failing,+ stalenessSweepIntervalMs: 100,+ home,+ });+ await saveOverOutsideWrite(rig);+ await pollUntil(+ async () => (await noticesFor(rig.s, kase.file)).some((n) => n.kind === 'save-held'),+ 10_000,+ 25,+ 'the held-save notice',+ );+ expect(readFileSync(rig.path, 'utf-8')).toBe(kase.outside);++ failing = false;++ await pollUntil(+ () => readFileSync(rig.path, 'utf-8') === here,+ 10_000,+ 25,+ 'the retried save to write the edits',+ );+ expect(await historyVersions(rig.s, kase.file)).toEqual([+ {+ kind: 'external-change-no-engine',+ side: 'theirs',+ fileType: 'mermaid',+ content: kase.outside,+ },+ ]);+ expect(await noticesFor(rig.s, kase.file)).toEqual([+ expect.objectContaining({ kind: 'moved-to-history', reason: 'no-merge-engine' }),+ ]);+ });++ test('a held save is retried and lands once the backup folder can take the outside version', async () => {+ const home = ownHome();+ blockBackups(home);+ const rig = await openSaved(kase.file, kase.saved, {+ historyFails: () => true,+ stalenessSweepIntervalMs: 100,+ home,+ });+ await saveOverOutsideWrite(rig);+ await pollUntil(+ async () => (await noticesFor(rig.s, kase.file)).some((n) => n.kind === 'save-held'),+ 10_000,+ 25,+ 'the held-save notice',+ );++ unblockBackups(home);++ await pollUntil(+ () => readFileSync(rig.path, 'utf-8') === here,+ 10_000,+ 25,+ 'the retried save to write the edits',+ );+ expect(backupsIn(home)).toEqual([kase.outside]);+ expect(await noticesFor(rig.s, kase.file)).toEqual([+ expect.objectContaining({ kind: 'moved-to-backup', reason: 'no-merge-engine' }),+ ]);+ });+});++describe('a held save on a document that already shows a kept-version notice', () => {+ const kase = CASES[0];+ const here = kase.saved.replace(kase.edit.find, kase.edit.replace);++ test('shows both notices while the hold lasts, and the kept-version notice stays when it clears', async () => {+ const home = ownHome();+ let failing = false;+ const rig = await openSaved(kase.file, kase.saved, {+ historyFails: () => failing,+ stalenessSweepIntervalMs: 100,+ home,+ });+ editInClient(rig.c, kase.edit.find, kase.edit.replace);+ await pollUntil(() => liveText(rig.s, kase.file) === here, 10_000, 25, 'the edit');+ writeFileSync(rig.path, kase.outside, 'utf-8');+ await flushPendingStore(rig.s, kase.file);+ await pollUntil(() => readFileSync(rig.path, 'utf-8') === here, 10_000, 25, 'the first save');++ failing = true;+ blockBackups(home);+ const again = here.replace('A-->C', 'A-->E');+ editInClient(rig.c, 'A-->C', 'A-->E');+ await pollUntil(() => liveText(rig.s, kase.file) === again, 10_000, 25, 'the second edit');+ writeFileSync(rig.path, 'graph TD\n A-->F\n', 'utf-8');+ await flushPendingStore(rig.s, kase.file);+ await pollUntil(+ async () => (await noticesFor(rig.s, kase.file)).some((n) => n.kind === 'save-held'),+ 10_000,+ 25,+ 'the held-save notice',+ );+ expect((await noticesFor(rig.s, kase.file)).map((n) => n.kind).sort()).toEqual([+ 'moved-to-history',+ 'save-held',+ ]);++ failing = false;++ await pollUntil(+ () => readFileSync(rig.path, 'utf-8') === again,+ 10_000,+ 25,+ 'the retried save to write the edits',+ );+ await pollUntil(+ async () => !(await noticesFor(rig.s, kase.file)).some((n) => n.kind === 'save-held'),+ 10_000,+ 25,+ 'the held-save notice to clear',+ );+ expect(await noticesFor(rig.s, kase.file)).toEqual([+ expect.objectContaining({ kind: 'moved-to-history', reason: 'no-merge-engine' }),+ ]);+ });+});++describe('an outside version that is not UTF-8', () => {+ const kase = CASES[2];+ const here = kase.saved.replace(kase.edit.find, kase.edit.replace);++ test('holds the save with a notice, is not retried at each sweep, and saves once the file changes', async () => {+ const home = ownHome();+ const rig = await openSaved(kase.file, kase.saved, { stalenessSweepIntervalMs: 50, home });+ editInClient(rig.c, kase.edit.find, kase.edit.replace);+ await pollUntil(() => liveText(rig.s, kase.file) === here, 10_000, 25, 'the edit');+ const utf16 = Buffer.from('\ufefffirst line\r\n', 'utf16le');+ writeFileSync(rig.path, utf16);+ await flushPendingStore(rig.s, kase.file);+ await pollUntil(+ async () => (await noticesFor(rig.s, kase.file)).some((n) => n.kind === 'save-held'),+ 10_000,+ 25,+ 'the held-save notice',+ );+ expect(await noticesFor(rig.s, kase.file)).toEqual([+ expect.objectContaining({ kind: 'save-held', cause: 'not-utf8' }),+ ]);+ const retriesBefore = getMetrics().heldSaveRetries;+ await new Promise((settle) => setTimeout(settle, 400));+ expect(getMetrics().heldSaveRetries).toBe(retriesBefore);+ expect(readFileSync(rig.path).equals(utf16)).toBe(true);++ writeFileSync(rig.path, kase.outside, 'utf-8');++ await pollUntil(+ () => readFileSync(rig.path, 'utf-8') === here,+ 10_000,+ 25,+ 'the save to land once the file changed',+ );+ expect(await historyVersions(rig.s, kase.file)).toEqual([+ {+ kind: 'external-change-no-engine',+ side: 'theirs',+ fileType: 'text',+ content: kase.outside,+ },+ ]);+ });+});++describe('an outside write to an open, unedited file with no merge engine', () => {+ const kase = CASES[0];++ test('a focus re-read applies it live with no history entry and no notice', async () => {+ const { s, c, path } = await openSaved(kase.file, kase.saved);+ writeFileSync(path, kase.outside, 'utf-8');++ const res = await fetch(`${s.baseUrl}/api/documents/refresh`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ docNames: [kase.file] }),+ });+ expect(await res.json()).toEqual({ checked: 1, found: 1 });++ await pollUntil(() => c.ytext.toString() === kase.outside, 10_000, 25, 'the re-read to apply');+ expect(await historyVersions(s, kase.file)).toEqual([]);+ expect(await noticesFor(s, kase.file)).toEqual([]);+ });++ test('a native change event applies it live', async () => {+ const { s, c, double, path } = await openSaved(kase.file, kase.saved);+ writeFileSync(path, kase.outside, 'utf-8');++ double.subscriptionFor(s.contentDir).deliver([{ type: 'update', path }]);++ await pollUntil(() => c.ytext.toString() === kase.outside, 10_000, 25, 'the event to apply');+ expect(await noticesFor(s, kase.file)).toEqual([]);+ });++ test('with native events silenced, the timed re-check applies it live', async () => {+ const { c, clock, path } = await openSaved(kase.file, kase.saved, {+ freshnessIntervalMs: 5_000,+ });+ writeFileSync(path, kase.outside, 'utf-8');++ clock.advance(5_000);++ await pollUntil(+ () => c.ytext.toString() === kase.outside,+ 10_000,+ 25,+ 'the timed re-check to apply the outside bytes',+ );+ expect(readFileSync(path, 'utf-8')).toBe(kase.outside);+ });+});diff --git a/packages/app/tests/integration/history-recorder-wiring.test.ts b/packages/app/tests/integration/history-recorder-wiring.test.tsnew file mode 100644index 000000000..93f8f7001--- /dev/null+++ b/packages/app/tests/integration/history-recorder-wiring.test.ts@@ -0,0 +1,148 @@+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { CONFIG_DOC_NAME_PROJECT } from '@inkeep/open-knowledge-core';+import { afterEach, describe, expect, test } from 'vitest';+import {+ type InMemoryCheckpointParams,+ saveInMemoryCheckpoint,+} from '../../../server/src/shadow-repo';+import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';+import {+ createTestClient,+ createTestServer,+ pollUntil,+ type TestClient,+ type TestServer,+} from './test-harness';++let server: TestServer | undefined;+const clients: TestClient[] = [];+const ownedDirs: string[] = [];++afterEach(async () => {+ for (const c of clients.splice(0)) await c.cleanup();+ await server?.cleanup();+ server = undefined;+ for (const dir of ownedDirs.splice(0)) rmSync(dir, { recursive: true, force: true });+});++function edit(c: TestClient, find: string, replace: string): void {+ c.doc.transact(() => {+ const at = c.ytext.toString().indexOf(find);+ c.ytext.delete(at, find.length);+ c.ytext.insert(at, replace);+ });+}++async function flushPendingStore(s: TestServer, docName: string): Promise<void> {+ const id = `onStoreDocument-${docName}`;+ if (s.instance.hocuspocus.debouncer.isDebounced(id)) {+ await s.instance.hocuspocus.debouncer.executeNow(id);+ }+}++describe('the server hands its history recorder to the stores that move versions to history', () => {+ test('engine-less, global skill and settings changes all write through the server recorder', async () => {+ const writes: Array<Pick<InMemoryCheckpointParams, 'kind' | 'docName'>> = [];+ const home = realpathSync(mkdtempSync(join(tmpdir(), 'ok-wiring-home-')));+ ownedDirs.push(home);+ const skillPath = join(home, '.claude', 'skills', 'demo', 'SKILL.md');+ mkdirSync(join(skillPath, '..'), { recursive: true });+ const skillSaved = '---\nname: demo\ndescription: d\n---\n\n# Demo\n\nFirst.\n';+ writeFileSync(skillPath, skillSaved, 'utf-8');+ const settingsSaved = 'contentRules:\n markdownlint:\n enabled: true\n';+ const s = await createTestServer({+ gitEnabled: true,+ configHomedirOverride: home,+ seedProjectConfigYml: settingsSaved,+ watcherBackend: createWatcherDouble().backend,+ debounce: 300_000,+ maxDebounce: 600_000,+ mergeHistoryWriter: (shadow, contentRoot, params) => {+ writes.push({ kind: params.kind, docName: params.docName });+ return saveInMemoryCheckpoint(shadow, contentRoot, params);+ },+ });+ server = s;++ const diagramPath = join(s.contentDir, 'flow.mmd');+ writeFileSync(diagramPath, 'graph TD\n A-->B\n', 'utf-8');+ const diagram = await createTestClient(s.port, 'flow.mmd', { skipInvariantWatcher: true });+ clients.push(diagram);+ await pollUntil(+ () => diagram.ytext.toString() === 'graph TD\n A-->B\n',+ 10_000,+ 25,+ 'flow.mmd',+ );+ edit(diagram, 'A-->B', 'A-->C');+ await pollUntil(+ () =>+ s.instance.hocuspocus.documents.get('flow.mmd')?.getText('source').toString() ===+ 'graph TD\n A-->C\n',+ 10_000,+ 25,+ 'the diagram edit to reach the server',+ );+ writeFileSync(diagramPath, 'graph TD\n A-->D\n', 'utf-8');+ await flushPendingStore(s, 'flow.mmd');++ const skill = await createTestClient(s.port, '__skill__/global/demo', {+ skipInvariantWatcher: true,+ });+ clients.push(skill);+ await pollUntil(() => skill.ytext.toString() === skillSaved, 10_000, 25, 'the skill');+ edit(skill, 'First.', 'First, here.');+ await pollUntil(+ () =>+ s.instance.hocuspocus.documents+ .get('__skill__/global/demo')+ ?.getText('source')+ .toString()+ .includes('First, here.') === true,+ 10_000,+ 25,+ 'the skill edit to reach the server',+ );+ writeFileSync(skillPath, skillSaved.replace('First.', 'First, outside.'), 'utf-8');+ await flushPendingStore(s, '__skill__/global/demo');++ const settings = await createTestClient(s.port, CONFIG_DOC_NAME_PROJECT, {+ skipInvariantWatcher: true,+ });+ clients.push(settings);+ await pollUntil(() => settings.ytext.toString() === settingsSaved, 10_000, 25, 'settings');+ settings.ytext.insert(settings.ytext.length, '# note\n');+ await pollUntil(+ () =>+ s.instance.hocuspocus.documents+ .get(CONFIG_DOC_NAME_PROJECT)+ ?.getText('source')+ .toString()+ .endsWith('# note\n') === true,+ 10_000,+ 25,+ 'the settings edit to reach the server',+ );+ writeFileSync(+ join(s.contentDir, '.ok', 'config.yml'),+ 'contentRules:\n markdownlint:\n enabled: false\n',+ 'utf-8',+ );++ await pollUntil(+ () => writes.length >= 4,+ 10_000,+ 25,+ 'four history writes through the server recorder',+ );+ expect(writes).toEqual(+ expect.arrayContaining([+ { kind: 'external-change-no-engine', docName: 'flow.mmd' },+ { kind: 'external-change-both-kept', docName: '__skill__/global/demo' },+ { kind: 'external-change-no-engine', docName: CONFIG_DOC_NAME_PROJECT },+ ]),+ );+ });+});diff --git a/packages/app/tests/integration/managed-skill-outside-change.test.ts b/packages/app/tests/integration/managed-skill-outside-change.test.tsnew file mode 100644index 000000000..4934fe27b--- /dev/null+++ b/packages/app/tests/integration/managed-skill-outside-change.test.ts@@ -0,0 +1,204 @@+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { afterEach, describe, expect, test } from 'vitest';+import {+ registerExternalSkill,+ unregisterExternalSkill,+} from '../../../server/src/external-skill-registry';+import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';+import {+ createTestClient,+ createTestServer,+ pollUntil,+ type TestClient,+ type TestServer,+} from './test-harness';++let server: TestServer | undefined;+let client: TestClient | undefined;+const ownedDirs: string[] = [];++afterEach(async () => {+ await client?.cleanup();+ client = undefined;+ await server?.cleanup();+ server = undefined;+ unregisterExternalSkill('ext-demo');+ for (const dir of ownedDirs.splice(0)) rmSync(dir, { recursive: true, force: true });+});++const SAVED =+ '---\nname: demo\ndescription: synthetic skill\n---\n\n# Demo\n\nFirst paragraph.\n\nSecond paragraph.\n';+const HERE = SAVED.replace('First paragraph.', 'First paragraph, edited here.');+const OUTSIDE = SAVED.replace('First paragraph.', 'First paragraph, edited outside.');+const BOTH_KEPT = SAVED.replace(+ 'First paragraph.',+ 'First paragraph, edited here.\n\nFirst paragraph, edited outside.',+);+const DOC = '__skill__/global/demo';++function ownedDir(prefix: string): string {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));+ ownedDirs.push(dir);+ return dir;+}++function liveText(s: TestServer, docName: string): string | null {+ return s.instance.hocuspocus.documents.get(docName)?.getText('source').toString() ?? null;+}++async function startWithGlobalSkill(): Promise<{ s: TestServer; path: string }> {+ const home = ownedDir('ok-skill-home-');+ const path = join(home, '.claude', 'skills', 'demo', 'SKILL.md');+ mkdirSync(join(path, '..'), { recursive: true });+ writeFileSync(path, SAVED, 'utf-8');+ const s = await createTestServer({+ gitEnabled: true,+ configHomedirOverride: home,+ watcherBackend: createWatcherDouble().backend,+ debounce: 300_000,+ maxDebounce: 600_000,+ });+ server = s;+ return { s, path };+}++async function openAndEdit(s: TestServer, docName: string, edit: boolean): Promise<TestClient> {+ const c = await createTestClient(s.port, docName, { skipInvariantWatcher: true });+ client = c;+ await pollUntil(() => c.ytext.toString() === SAVED, 10_000, 25, `${docName} to load`);+ if (edit) {+ c.doc.transact(() => {+ const at = c.ytext.toString().indexOf('First paragraph.');+ c.ytext.delete(at, 'First paragraph.'.length);+ c.ytext.insert(at, 'First paragraph, edited here.');+ });+ await pollUntil(+ () => liveText(s, docName) === HERE,+ 10_000,+ 25,+ 'the edit to reach the server',+ );+ }+ return c;+}++async function flushPendingStore(s: TestServer, docName: string): Promise<void> {+ const id = `onStoreDocument-${docName}`;+ if (s.instance.hocuspocus.debouncer.isDebounced(id)) {+ await s.instance.hocuspocus.debouncer.executeNow(id);+ }+}++async function bothKeptHistory(s: TestServer, docName: string): Promise<string[]> {+ let rows: Array<{ sha: string; checkpoint?: { kind?: string } }> = [];+ await pollUntil(+ async () => {+ const res = await fetch(+ `${s.baseUrl}/api/history?docName=${encodeURIComponent(docName)}&type=checkpoint&limit=100`,+ );+ const body = (await res.json()) as { entries?: typeof rows };+ rows = (body.entries ?? []).filter(+ (row) => row.checkpoint?.kind === 'external-change-both-kept',+ );+ return rows.length >= 2;+ },+ 10_000,+ 50,+ 'both pre-merge versions in history',+ );+ const contents: string[] = [];+ for (const row of rows) {+ const body = await fetch(+ `${s.baseUrl}/api/history/${row.sha}?docName=${encodeURIComponent(docName)}`,+ ).then((r) => r.json() as Promise<{ content: string }>);+ contents.push(body.content);+ }+ return contents.sort();+}++async function noticesFor(s: TestServer, docName: string): Promise<Array<Record<string, unknown>>> {+ const res = await fetch(`${s.baseUrl}/api/doc-notices`);+ const body = (await res.json()) as { notices?: Array<Record<string, unknown>> };+ return (body.notices ?? []).filter((notice) => notice.docName === docName);+}++describe('an outside change to a global skill', () => {+ test('a same-block collision at the save keeps both versions live and on disk, with history and a notice', async () => {+ const { s, path } = await startWithGlobalSkill();+ await openAndEdit(s, DOC, true);+ writeFileSync(path, OUTSIDE, 'utf-8');++ await flushPendingStore(s, DOC);++ await pollUntil(+ () => readFileSync(path, 'utf-8') === BOTH_KEPT,+ 10_000,+ 25,+ 'both kept on disk',+ );+ expect(liveText(s, DOC)).toBe(BOTH_KEPT);+ expect(await bothKeptHistory(s, DOC)).toEqual([HERE, OUTSIDE].sort());+ expect(await noticesFor(s, DOC)).toEqual([+ expect.objectContaining({ kind: 'both-kept', file: '~/.claude/skills/demo/SKILL.md' }),+ ]);+ });++ test('a same-block collision at the polled intake keeps both versions live and on disk', async () => {+ const { s, path } = await startWithGlobalSkill();+ await openAndEdit(s, DOC, true);+ writeFileSync(path, OUTSIDE, 'utf-8');++ await pollUntil(() => liveText(s, DOC) === BOTH_KEPT, 10_000, 25, 'the intake to keep both');+ await pollUntil(+ () => readFileSync(path, 'utf-8') === BOTH_KEPT,+ 10_000,+ 25,+ 'both kept on disk',+ );+ expect(await bothKeptHistory(s, DOC)).toEqual([HERE, OUTSIDE].sort());+ });++ test('a refresh of a skill nobody edited applies with no notice', async () => {+ const { s, path } = await startWithGlobalSkill();+ await openAndEdit(s, DOC, false);+ const refreshed = SAVED.replace('Second paragraph.', 'Second paragraph, refreshed.');+ writeFileSync(path, refreshed, 'utf-8');++ await pollUntil(() => liveText(s, DOC) === refreshed, 10_000, 25, 'the refresh to apply');+ expect(readFileSync(path, 'utf-8')).toBe(refreshed);+ expect(await noticesFor(s, DOC)).toEqual([]);+ });+});++describe('an outside change to an external skill', () => {+ test('a same-block collision at the save keeps both versions', async () => {+ const skillDir = ownedDir('ok-ext-skill-');+ const path = join(skillDir, 'SKILL.md');+ writeFileSync(path, SAVED, 'utf-8');+ registerExternalSkill('ext-demo', skillDir);+ const s = await createTestServer({+ gitEnabled: true,+ configHomedirOverride: ownedDir('ok-ext-home-'),+ watcherBackend: createWatcherDouble().backend,+ debounce: 300_000,+ maxDebounce: 600_000,+ });+ server = s;+ const docName = '__extskill__/ext-demo';+ await openAndEdit(s, docName, true);+ writeFileSync(path, OUTSIDE, 'utf-8');++ await flushPendingStore(s, docName);++ await pollUntil(+ () => readFileSync(path, 'utf-8') === BOTH_KEPT,+ 10_000,+ 25,+ 'both kept on disk',+ );+ expect(liveText(s, docName)).toBe(BOTH_KEPT);+ expect(await bothKeptHistory(s, docName)).toEqual([HERE, OUTSIDE].sort());+ });+});diff --git a/packages/app/tests/integration/settings-outside-change.test.ts b/packages/app/tests/integration/settings-outside-change.test.tsnew file mode 100644index 000000000..347a530a1--- /dev/null+++ b/packages/app/tests/integration/settings-outside-change.test.ts@@ -0,0 +1,165 @@+import {+ existsSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ realpathSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { CONFIG_DOC_NAME_PROJECT } from '@inkeep/open-knowledge-core';+import { afterEach, describe, expect, test } from 'vitest';+import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';+import {+ createTestClient,+ createTestServer,+ pollUntil,+ type TestClient,+ type TestServer,+} from './test-harness';++let server: TestServer | undefined;+let client: TestClient | undefined;+let home: string | undefined;++afterEach(async () => {+ await client?.cleanup();+ client = undefined;+ await server?.cleanup();+ server = undefined;+ if (home !== undefined) rmSync(home, { recursive: true, force: true });+ home = undefined;+});++const SAVED = 'contentRules:\n markdownlint:\n enabled: true\n';+const PENDING = `${SAVED}# a note being typed\n`;++function liveText(s: TestServer): string | null {+ return (+ s.instance.hocuspocus.documents.get(CONFIG_DOC_NAME_PROJECT)?.getText('source').toString() ??+ null+ );+}++async function openWithPendingEdit(+ options: { historyFails?: boolean; home?: string } = {},+): Promise<{ s: TestServer; path: string }> {+ const s = await createTestServer({+ gitEnabled: true,+ configHomedirOverride: options.home,+ mergeHistoryWriter: options.historyFails+ ? () => Promise.reject(new Error('history is unavailable'))+ : undefined,+ seedProjectConfigYml: SAVED,+ watcherBackend: createWatcherDouble().backend,+ debounce: 300_000,+ maxDebounce: 600_000,+ });+ server = s;+ const c = await createTestClient(s.port, CONFIG_DOC_NAME_PROJECT, { skipInvariantWatcher: true });+ client = c;+ await pollUntil(() => c.ytext.toString() === SAVED, 10_000, 25, 'the settings to load');+ c.ytext.insert(c.ytext.length, '# a note being typed\n');+ await pollUntil(() => liveText(s) === PENDING, 10_000, 25, 'the edit to reach the server');+ return { s, path: join(s.contentDir, '.ok', 'config.yml') };+}++async function settingsHistory(+ s: TestServer,+): Promise<Array<{ side: unknown; fileType: unknown; content: string }>> {+ const docName = encodeURIComponent(CONFIG_DOC_NAME_PROJECT);+ const res = await fetch(`${s.baseUrl}/api/history?docName=${docName}&type=checkpoint&limit=100`);+ const body = (await res.json()) as {+ entries?: Array<{ sha: string; checkpoint?: { metadata?: Record<string, unknown> } }>;+ };+ const versions: Array<{ side: unknown; fileType: unknown; content: string }> = [];+ for (const row of body.entries ?? []) {+ const content = await fetch(`${s.baseUrl}/api/history/${row.sha}?docName=${docName}`).then(+ (r) => r.json() as Promise<{ content: string }>,+ );+ versions.push({+ side: row.checkpoint?.metadata?.side,+ fileType: row.checkpoint?.metadata?.fileType,+ content: content.content,+ });+ }+ return versions;+}++async function settingsNotices(s: TestServer): Promise<Array<Record<string, unknown>>> {+ const res = await fetch(`${s.baseUrl}/api/doc-notices`);+ const body = (await res.json()) as { notices?: Array<Record<string, unknown>> };+ return (body.notices ?? []).filter((notice) => notice.docName === CONFIG_DOC_NAME_PROJECT);+}++describe('an outside change to the project settings under an unsaved edit', () => {+ test('a valid outside version applies, and the unsaved edit goes to history with a notice', async () => {+ const { s, path } = await openWithPendingEdit();+ const outside = 'contentRules:\n markdownlint:\n enabled: false\n';+ writeFileSync(path, outside, 'utf-8');++ await pollUntil(() => liveText(s) === outside, 10_000, 25, 'the polled intake to apply');+ expect(readFileSync(path, 'utf-8')).toBe(outside);+ await pollUntil(async () => (await settingsNotices(s)).length === 1, 10_000, 25, 'the notice');+ expect(await settingsHistory(s)).toEqual([+ { side: 'ours', fileType: 'config', content: PENDING },+ ]);+ expect(await settingsNotices(s)).toEqual([+ expect.objectContaining({+ kind: 'moved-to-history',+ side: 'ours',+ reason: 'outside-settings-applied',+ file: '.ok/config.yml',+ }),+ ]);+ });++ test('an invalid outside version never wins: it goes to history and the edit is written', async () => {+ const { s, path } = await openWithPendingEdit();+ const invalid = 'contentRules: [unclosed\n';+ writeFileSync(path, invalid, 'utf-8');+ const id = `onStoreDocument-${CONFIG_DOC_NAME_PROJECT}`;+ if (s.instance.hocuspocus.debouncer.isDebounced(id)) {+ await s.instance.hocuspocus.debouncer.executeNow(id);+ }++ await pollUntil(() => readFileSync(path, 'utf-8') === PENDING, 10_000, 25, 'the edit on disk');+ expect(liveText(s)).toBe(PENDING);+ expect(await settingsHistory(s)).toEqual([+ { side: 'theirs', fileType: 'config', content: invalid },+ ]);+ expect(await settingsNotices(s)).toEqual([+ expect.objectContaining({ reason: 'outside-settings-invalid', file: '.ok/config.yml' }),+ ]);+ });++ test('when history cannot take the unsaved edit, a valid outside version applies once the edit is in the backup folder', async () => {+ home = realpathSync(mkdtempSync(join(tmpdir(), 'ok-settings-home-')));+ const { s, path } = await openWithPendingEdit({ historyFails: true, home });+ const outside = 'contentRules:\n markdownlint:\n enabled: false\n';+ writeFileSync(path, outside, 'utf-8');++ await pollUntil(() => liveText(s) === outside, 10_000, 25, 'the polled intake to apply');+ await pollUntil(async () => (await settingsNotices(s)).length === 1, 10_000, 25, 'the notice');+ const backups = join(home, '.ok', 'edit-backups', 'discarded');+ expect(existsSync(backups)).toBe(true);+ expect(+ readdirSync(backups, { recursive: true, withFileTypes: true })+ .filter((entry) => entry.isFile())+ .map((entry) => readFileSync(join(entry.parentPath, entry.name), 'utf-8')),+ ).toEqual([PENDING]);+ expect(await settingsNotices(s)).toEqual([+ expect.objectContaining({+ kind: 'moved-to-backup',+ side: 'ours',+ reason: 'outside-settings-applied',+ file: '.ok/config.yml',+ backup: expect.stringMatching(+ /^~\/\.ok\/edit-backups\/discarded\/projects\/[0-9a-f]{8}\/[^/]+\/[^/]+\.yml$/,+ ),+ }),+ ]);+ });+});diff --git a/packages/core/src/checkpoint-kind-registry.test.ts b/packages/core/src/checkpoint-kind-registry.test.tsindex 51bdac565..bc69a6924 100644--- a/packages/core/src/checkpoint-kind-registry.test.ts+++ b/packages/core/src/checkpoint-kind-registry.test.ts@@ -19,6 +19,27 @@ describe('checkpoint-kind registry', () => {expect([...CHECKPOINT_KINDS].sort()).toEqual(Object.keys(SAMPLE_BY_KIND).sort());});+ it('reads every kept-live reason and every no-engine file type, and nothing else', () => {+ const line = (kind: string, metadata: Record<string, string>) =>+ `ok-checkpoint-v1: ${JSON.stringify({ kind, docName: 'x', size: 1, metadata })}`;+ for (const reason of ['check-failed', 'too-large', 'conflict-markers', 'no-base']) {+ expect(+ parseCheckpoint(line('external-change-kept-live', { side: 'theirs', reason }))?.kind,+ ).toBe('external-change-kept-live');+ }+ for (const fileType of ['mermaid', 'excalidraw', 'text', 'config']) {+ expect(+ parseCheckpoint(line('external-change-no-engine', { side: 'ours', fileType }))?.kind,+ ).toBe('external-change-no-engine');+ }+ expect(+ parseCheckpoint(line('external-change-kept-live', { side: 'theirs', reason: 'other' })),+ ).toBeNull();+ expect(+ parseCheckpoint(line('external-change-no-engine', { side: 'theirs', fileType: 'pdf' })),+ ).toBeNull();+ });+it('gives every kind a complete, well-typed attribute set', () => {for (const kind of CHECKPOINT_KINDS) {const attrs = CHECKPOINT_KIND_REGISTRY[kind];diff --git a/packages/core/src/checkpoint-kinds.ts b/packages/core/src/checkpoint-kinds.tsindex c3dc902f3..a50a865db 100644--- a/packages/core/src/checkpoint-kinds.ts+++ b/packages/core/src/checkpoint-kinds.ts@@ -2,6 +2,12 @@ const OK_CHECKPOINT_PREFIX = 'ok-checkpoint-v1: ';export type AutoConsolidationTrigger = 'dead-chain' | 'session-close' | 'boot' | 'ttl';+const KEPT_LIVE_REASONS = ['check-failed', 'too-large', 'conflict-markers', 'no-base'] as const;+type KeptLiveReason = (typeof KEPT_LIVE_REASONS)[number];++const NO_ENGINE_FILE_TYPES = ['mermaid', 'excalidraw', 'text', 'config'] as const;+type NoEngineFileType = (typeof NO_ENGINE_FILE_TYPES)[number];+export type ParsedCheckpoint =| {kind: 'bridge-merge-loss';@@ -91,7 +97,13 @@ export type ParsedCheckpoint =kind: 'external-change-kept-live';docName: string | null;size: number | null;- metadata: { side: 'ours' | 'theirs'; reason: 'check-failed' | 'too-large' };+ metadata: { side: 'ours' | 'theirs'; reason: KeptLiveReason };+ }+ | {+ kind: 'external-change-no-engine';+ docName: string | null;+ size: number | null;+ metadata: { side: 'ours' | 'theirs'; fileType: NoEngineFileType };}| {kind: 'auto-consolidation';@@ -104,6 +116,14 @@ function isMergeSide(value: unknown): value is 'ours' | 'theirs' {return value === 'ours' || value === 'theirs';}+function isKeptLiveReason(value: unknown): value is KeptLiveReason {+ return (KEPT_LIVE_REASONS as readonly unknown[]).includes(value);+}++function isNoEngineFileType(value: unknown): value is NoEngineFileType {+ return (NO_ENGINE_FILE_TYPES as readonly unknown[]).includes(value);+}+export function parseCheckpoint(body: string): ParsedCheckpoint | null {if (!body) return null;for (const line of body.split('\n')) {@@ -303,7 +323,7 @@ export function parseCheckpoint(body: string): ParsedCheckpoint | null {}if (kind === 'external-change-kept-live') {const m = metadata as { side?: unknown; reason?: unknown };- if (isMergeSide(m.side) && (m.reason === 'check-failed' || m.reason === 'too-large')) {+ if (isMergeSide(m.side) && isKeptLiveReason(m.reason)) {return {kind: 'external-change-kept-live',docName,@@ -313,6 +333,18 @@ export function parseCheckpoint(body: string): ParsedCheckpoint | null {}return null;}+ if (kind === 'external-change-no-engine') {+ const m = metadata as { side?: unknown; fileType?: unknown };+ if (isMergeSide(m.side) && isNoEngineFileType(m.fileType)) {+ return {+ kind: 'external-change-no-engine',+ docName,+ size,+ metadata: { side: m.side, fileType: m.fileType },+ };+ }+ return null;+ }if (kind === 'auto-consolidation') {const m = metadata as { foldedRefs?: unknown; trigger?: unknown };if (@@ -457,6 +489,12 @@ export const CHECKPOINT_KIND_REGISTRY = {bundleExposure: 'metadata',chainAnchor: false,},+ 'external-change-no-engine': {+ visibility: 'surfaced',+ gcBucket: 'external-change-no-engine',+ bundleExposure: 'metadata',+ chainAnchor: false,+ },'auto-consolidation': {visibility: 'hidden',gcBucket: 'auto-consolidation',@@ -558,6 +596,12 @@ export const CHECKPOINT_SAMPLE_BY_KIND = {size: 12,metadata: { side: 'theirs', reason: 'check-failed' },},+ 'external-change-no-engine': {+ kind: 'external-change-no-engine',+ docName: 'flow.mmd',+ size: 12,+ metadata: { side: 'theirs', fileType: 'mermaid' },+ },'auto-consolidation': {kind: 'auto-consolidation',docName: null,diff --git a/packages/core/src/config/errors.ts b/packages/core/src/config/errors.tsindex 9c5028d09..e900c13ec 100644--- a/packages/core/src/config/errors.ts+++ b/packages/core/src/config/errors.ts@@ -91,6 +91,11 @@ export const KnownConfigValidationErrorSchema = z.discriminatedUnion('code', [detail: z.string(),lineNumber: z.number().int().min(1).optional(),}),+ z.object({+ code: z.literal('SAVE_HELD'),+ cause: z.enum(['no-history-or-backup', 'keeps-changing', 'not-utf8', 'unreadable']),+ file: z.string(),+ }),z.object({code: z.literal('UNKNOWN'),message: z.string().optional(),@@ -310,6 +315,8 @@ export function humanFormat(error: ConfigValidationError): string {return error.lineNumber !== undefined? `.okignore line ${error.lineNumber}: ${error.detail}`: `.okignore: ${error.detail}`;+ case 'SAVE_HELD':+ return `${error.file} was not saved (${error.cause}); saving is tried again.`;case 'UNKNOWN':return error.message ?? 'Unknown error.';}diff --git a/packages/core/src/schemas/api/doc-notices.ts b/packages/core/src/schemas/api/doc-notices.tsindex 3e14b5cc3..e419f5f0c 100644--- a/packages/core/src/schemas/api/doc-notices.ts+++ b/packages/core/src/schemas/api/doc-notices.ts@@ -2,7 +2,21 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';import { z } from 'zod';const DOC_NOTICE_SIDES = ['ours', 'theirs'] as const;-const DOC_NOTICE_MOVE_REASONS = ['check-failed', 'too-large'] as const;+const DOC_NOTICE_MOVE_REASONS = [+ 'check-failed',+ 'too-large',+ 'conflict-markers',+ 'no-base',+ 'no-merge-engine',+ 'outside-settings-applied',+ 'outside-settings-invalid',+] as const;+const DOC_NOTICE_HOLD_CAUSES = [+ 'no-history-or-backup',+ 'keeps-changing',+ 'not-utf8',+ 'unreadable',+] as const;const DocNoticeKeptBlocksSchema = z.object({duplicated: z.number().int().nonnegative(),@@ -36,6 +50,22 @@ export const DocNoticeWireSchema = z.discriminatedUnion('kind', [reason: z.enum(DOC_NOTICE_MOVE_REASONS),}).loose(),+ z+ .object({+ ...docNoticeCommon,+ kind: z.literal('moved-to-backup'),+ side: z.enum(DOC_NOTICE_SIDES),+ reason: z.enum(DOC_NOTICE_MOVE_REASONS),+ backup: z.string().min(1),+ })+ .loose(),+ z+ .object({+ ...docNoticeCommon,+ kind: z.literal('save-held'),+ cause: z.enum(DOC_NOTICE_HOLD_CAUSES),+ })+ .loose(),]) satisfies StandardSchemaV1;export type DocNoticeWire = z.infer<typeof DocNoticeWireSchema>;diff --git a/packages/core/src/util/atomic-yaml-write.test.ts b/packages/core/src/util/atomic-yaml-write.test.tsindex 44d83ce64..73b42bdec 100644--- a/packages/core/src/util/atomic-yaml-write.test.ts+++ b/packages/core/src/util/atomic-yaml-write.test.ts@@ -77,6 +77,33 @@ describe('atomicWriteFile (async) — sequential', () => {});});+describe('atomicWriteFile (async) — the check before the rename', () => {+ test('runs after the temp file is written and before the target is replaced', async () => {+ writeFileSync(target, 'before\n');+ const seen: Array<{ target: string; tmps: number }> = [];+ await atomicWriteFile(target, 'after\n', {+ beforeRename: () => {+ seen.push({ target: readFileSync(target, 'utf-8'), tmps: orphanTmps().length });+ },+ });+ expect(seen).toEqual([{ target: 'before\n', tmps: 1 }]);+ expect(readFileSync(target, 'utf-8')).toBe('after\n');+ });++ test('a check that throws leaves the target untouched and removes the temp file', async () => {+ writeFileSync(target, 'outside\n');+ await expect(+ atomicWriteFile(target, 'ours\n', {+ beforeRename: () => {+ throw new Error('the target moved');+ },+ }),+ ).rejects.toThrow('the target moved');+ expect(readFileSync(target, 'utf-8')).toBe('outside\n');+ expect(orphanTmps()).toEqual([]);+ });+});+describe('atomicWriteFile (async) — failure cleanup', () => {test('cleans tmp when rename fails because target is a non-empty dir', async () => {mkdirSync(target, { recursive: true });diff --git a/packages/core/src/util/atomic-yaml-write.ts b/packages/core/src/util/atomic-yaml-write.tsindex 3ccd87276..9c1f4862e 100644--- a/packages/core/src/util/atomic-yaml-write.ts+++ b/packages/core/src/util/atomic-yaml-write.ts@@ -29,6 +29,7 @@ export interface AtomicWriteOptions {mode?: number;sweepStaleTmps?: boolean;fs?: AtomicWriteFsAdapter;+ beforeRename?: () => void;}export interface AtomicWriteSyncOptions {@@ -80,6 +81,7 @@ export async function atomicWriteFile(const tmpPath = atomicTempPath(absPath);try {await fs.writeFile(tmpPath, content, { encoding: 'utf-8', mode: opts.mode ?? 0o644 });+ opts.beforeRename?.();await fs.rename(tmpPath, absPath);} catch (e) {try {diff --git a/packages/server/src/config-persistence.test.ts b/packages/server/src/config-persistence.test.tsindex e08b647b8..3a1f46480 100644--- a/packages/server/src/config-persistence.test.ts+++ b/packages/server/src/config-persistence.test.ts@@ -17,7 +17,7 @@ import {type ConfigValidationError,isKnownConfigError,} from '@inkeep/open-knowledge-core';-import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import * as Y from 'yjs';import {CONFIG_FILE_WATCHER_ORIGIN,@@ -32,15 +32,59 @@ import {loadConfigDoc,storeConfigDoc,} from './config-persistence.ts';+import * as fsTraced from './fs-traced.ts';+import { getMetrics, resetMetrics } from './metrics.ts';++interface MovedConfigVersion {+ docName: string;+ side: 'ours' | 'theirs';+ bytes: string;+ fileType: string;+}interface Fixture {projectDir: string;homedir: string;rejections: Array<{ docName: string; error: ConfigValidationError }>;+ moved: MovedConfigVersion[];ctx: ConfigPersistenceCtx;cleanup: () => void;}+interface NoticedConfigVersion {+ docName: string;+ side: string;+ where: 'history' | 'backup';+ entry: string;+}++const noticed: NoticedConfigVersion[] = [];+let duringSave: (() => void) | null = null;++function recordingHistory(+ moved: MovedConfigVersion[],+ saves: () => boolean = () => true,+): NonNullable<ConfigPersistenceCtx['history']> {+ return {+ saveNoEngine: async (docName, displaced, fileType) => {+ duringSave?.();+ if (!saves()) return null;+ moved.push({ docName, ...displaced, fileType });+ return `entry-${moved.length}`;+ },+ noticeNoEngine: (docName, side, _fileType, copy) => {+ noticed.push({+ docName,+ side,+ where: copy.where,+ entry: copy.where === 'history' ? copy.entry : copy.backup.display,+ });+ },+ };+}++let historySaves = true;+function makeFixture(): Fixture {const root = mkdtempSync(join(tmpdir(), 'ok-config-persist-'));const projectDir = join(root, 'project');@@ -48,18 +92,25 @@ function makeFixture(): Fixture {mkdirSync(projectDir, { recursive: true });mkdirSync(homedir, { recursive: true });const rejections: Fixture['rejections'] = [];+ const moved: MovedConfigVersion[] = [];+ historySaves = true;+ noticed.length = 0;+ duringSave = null;const ctx: ConfigPersistenceCtx = {projectDir,lkgCache: new Map(),+ agreedDisk: new Map(),homedirOverride: homedir,onConfigRejected: (docName, error) => {rejections.push({ docName, error });},+ history: recordingHistory(moved, () => historySaves),};return {projectDir,homedir,rejections,+ moved,ctx,cleanup: () => {try {@@ -69,6 +120,19 @@ function makeFixture(): Fixture {};}+function backupsIn(home: string): string[] {+ const root = join(home, '.ok', 'edit-backups', 'discarded');+ if (!existsSync(root)) return [];+ return readdirSync(root, { recursive: true, withFileTypes: true })+ .filter((entry) => entry.isFile())+ .map((entry) => readFileSync(join(entry.parentPath, entry.name), 'utf-8'));+}++function blockBackups(home: string): void {+ mkdirSync(join(home, '.ok'), { recursive: true });+ writeFileSync(join(home, '.ok', 'edit-backups'), 'not a folder');+}+function writeWorkspaceConfig(projectDir: string, content: string): string {const path = join(projectDir, '.ok', 'config.yml');mkdirSync(dirname(path), { recursive: true });@@ -87,12 +151,167 @@ let fx: Fixture;beforeEach(() => {fx = makeFixture();+ resetMetrics();});afterEach(() => {+ vi.restoreAllMocks();fx.cleanup();});+describe('settings outside changes: agreed version, races and deferral', () => {+ const SAVED = 'mcp:\n autoStart: true\n';+ const EDIT = 'mcp:\n autoStart: true\n# note\n';++ function projectPath(): string {+ const path = configDocAbsPath(CONFIG_DOC_NAME_PROJECT, fx.ctx);+ mkdirSync(dirname(path), { recursive: true });+ return path;+ }++ function loaded(fileBytes: string | null): Y.Doc {+ const path = projectPath();+ if (fileBytes !== null) writeFileSync(path, fileBytes, 'utf-8');+ const doc = new Y.Doc();+ loadConfigDoc(doc, CONFIG_DOC_NAME_PROJECT, fx.ctx);+ return doc;+ }++ function type(doc: Y.Doc, text: string): void {+ const ytext = doc.getText('source');+ doc.transact(() => {+ ytext.delete(0, ytext.length);+ ytext.insert(0, text);+ }, 'person');+ }++ test('an empty settings file at load is not an outside change: the first edit is written', async () => {+ const doc = loaded('');+ type(doc, EDIT);++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_PROJECT, 'person', fx.ctx)).toBe('persisted');++ expect(readFileSync(projectPath(), 'utf-8')).toBe(EDIT);+ expect(doc.getText('source').toString()).toBe(EDIT);+ expect(fx.moved).toEqual([]);+ expect(noticed).toEqual([]);+ });++ test('a settings file that was invalid at load is not an outside change: the first valid edit is written', async () => {+ const doc = loaded('contentRules: [unclosed\n');+ type(doc, EDIT);++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_PROJECT, 'person', fx.ctx)).toBe('persisted');++ expect(readFileSync(projectPath(), 'utf-8')).toBe(EDIT);+ expect(fx.moved).toEqual([]);+ expect(noticed).toEqual([]);+ });++ test('two outside versions arriving during one history save end with the newer one applied, noticed once', async () => {+ const doc = loaded(SAVED);+ type(doc, EDIT);+ const w1 = 'mcp:\n autoStart: false\n';+ const w2 = 'mcp:\n autoStart: false\n# outside again\n';++ const [first, second] = await Promise.all([+ applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, w1, fx.ctx),+ applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, w2, fx.ctx),+ ]);++ expect([first, second]).toEqual(['applied', 'applied']);+ expect(doc.getText('source').toString()).toBe(w2);+ expect(fx.moved.map((version) => version.bytes)).toEqual([EDIT]);+ expect(noticed).toHaveLength(1);+ });++ test('typing through every history save defers the outside version to the pending save, with no notice', async () => {+ const doc = loaded(SAVED);+ type(doc, EDIT);+ let typed = 0;+ duringSave = () => {+ typed += 1;+ type(doc, `${EDIT}# still typing ${typed}\n`);+ };++ expect(+ await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ 'mcp:\n autoStart: false\n',+ fx.ctx,+ ),+ ).toBe('held');++ expect(doc.getText('source').toString()).toBe(`${EDIT}# still typing 3\n`);+ expect(fx.moved).toHaveLength(3);+ expect(noticed).toEqual([]);+ expect(getMetrics().configOutsideChange).toEqual({ 'intake:deferred': 1 });+ });++ test('an empty settings document has nothing unsaved for the intake to keep', async () => {+ const doc = loaded(SAVED);+ type(doc, '');++ expect(+ await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ 'mcp:\n autoStart: false\n',+ fx.ctx,+ ),+ ).toBe('applied');++ expect(fx.moved).toEqual([]);+ expect(getMetrics().configOutsideChange).toEqual({ 'intake:applied': 1 });+ });++ test('a valid outside version written during the history save of an invalid one wins, with the edit kept', async () => {+ const path = projectPath();+ const doc = loaded(SAVED);+ type(doc, EDIT);+ writeFileSync(path, 'mcp: [unclosed\n', 'utf-8');+ const later = 'mcp:\n autoStart: false\n';+ let planted = false;+ duringSave = () => {+ if (planted) return;+ planted = true;+ writeFileSync(path, later, 'utf-8');+ };++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_PROJECT, 'person', fx.ctx)).toBe('reconciled');++ expect(readFileSync(path, 'utf-8')).toBe(later);+ expect(doc.getText('source').toString()).toBe(later);+ expect(fx.moved.map((version) => [version.side, version.bytes])).toEqual([+ ['theirs', 'mcp: [unclosed\n'],+ ['ours', EDIT],+ ]);+ expect(noticed.map((notice) => notice.side)).toEqual(['ours']);+ });++ test('an outside version written between the compare and the rename is not written over', async () => {+ const path = projectPath();+ const doc = loaded(SAVED);+ type(doc, EDIT);+ const between = 'mcp:\n autoStart: false\n';+ const write = fsTraced.tracedWriteFile;+ let planted = false;+ vi.spyOn(fsTraced, 'tracedWriteFile').mockImplementation(async (...args) => {+ await write(...args);+ if (planted) return;+ planted = true;+ writeFileSync(path, between, 'utf-8');+ });++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_PROJECT, 'person', fx.ctx)).toBe('reconciled');++ expect(readFileSync(path, 'utf-8')).toBe(between);+ expect(fx.moved.map((version) => version.bytes)).toEqual([EDIT]);+ expect(getMetrics().storeRestatRefused).toBe(1);+ });+});+describe('configDocAbsPath', () => {test('project doc resolves under projectDir/.ok/config.yml', () => {expect(configDocAbsPath(CONFIG_DOC_NAME_PROJECT, fx.ctx)).toBe(@@ -250,22 +469,27 @@ describe('storeConfigDoc — cross-process reconciliation (file lock)', () => {function makeSecondCtxSharingHomedir(primary: Fixture): {ctx: ConfigPersistenceCtx;rejections: Array<{ docName: string; error: ConfigValidationError }>;+ moved: MovedConfigVersion[];} {const rejections: Array<{ docName: string; error: ConfigValidationError }> = [];+ const moved: MovedConfigVersion[] = [];return {rejections,+ moved,ctx: {projectDir: primary.projectDir,lkgCache: new Map(),+ agreedDisk: new Map(),homedirOverride: primary.homedir,onConfigRejected: (docName, error) => {rejections.push({ docName, error });},+ history: recordingHistory(moved),},};}- test('reconciles when disk diverged from LKG: imports disk into Y.Text and does NOT overwrite disk', async () => {+ test('a valid outside version wins at the store and the unsaved edit it displaces goes to history', async () => {const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);mkdirSync(dirname(path), { recursive: true });writeFileSync(path, 'mcp:\n autoStart: false\n', 'utf-8');@@ -281,6 +505,92 @@ describe('storeConfigDoc — cross-process reconciliation (file lock)', () => {expect(doc.getText('source').toString()).toBe('mcp:\n autoStart: false\n');expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_USER)).toBe('mcp:\n autoStart: false\n');expect(fx.rejections).toHaveLength(0);+ expect(fx.moved).toEqual([+ {+ docName: CONFIG_DOC_NAME_USER,+ side: 'ours',+ bytes: 'appearance:\n theme: dark\n',+ fileType: 'config',+ },+ ]);+ expect(getMetrics().configOutsideChange).toEqual({ 'store:applied-displaced': 1 });+ });++ test('a valid outside version that history cannot take applies once the unsaved edit is in the backup folder', async () => {+ const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, 'mcp:\n autoStart: false\n', 'utf-8');+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_USER, 'mcp:\n autoStart: true\n');+ historySaves = false;++ const doc = new Y.Doc();+ doc.getText('source').insert(0, 'appearance:\n theme: dark\n');++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_USER, undefined, fx.ctx)).toBe('reconciled');+ expect(doc.getText('source').toString()).toBe('mcp:\n autoStart: false\n');+ expect(backupsIn(fx.homedir)).toEqual(['appearance:\n theme: dark\n']);+ expect(noticed).toEqual([+ {+ docName: CONFIG_DOC_NAME_USER,+ side: 'ours',+ where: 'backup',+ entry: expect.stringMatching(+ /^~\/\.ok\/edit-backups\/discarded\/projects\/[0-9a-f]{8}\/[^/]+\/[^/]+\.yml$/,+ ),+ },+ ]);+ expect(getMetrics().configOutsideChange).toEqual({ 'store:applied-displaced': 1 });+ });++ test('a valid outside version that neither history nor the backup folder can take leaves the unsaved edit live and nothing written', async () => {+ const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, 'mcp:\n autoStart: false\n', 'utf-8');+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_USER, 'mcp:\n autoStart: true\n');+ historySaves = false;+ blockBackups(fx.homedir);++ const doc = new Y.Doc();+ doc.getText('source').insert(0, 'appearance:\n theme: dark\n');++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_USER, undefined, fx.ctx)).toEqual({+ kind: 'held',+ cause: 'no-history-or-backup',+ });+ expect(doc.getText('source').toString()).toBe('appearance:\n theme: dark\n');+ expect(readFileSync(path, 'utf-8')).toBe('mcp:\n autoStart: false\n');+ expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_USER)).toBe('mcp:\n autoStart: true\n');+ expect(noticed).toEqual([]);+ expect(getMetrics().configOutsideChange).toEqual({ 'store:held-no-history-or-backup': 1 });+ });++ test('an outside version that is not valid UTF-8 is neither applied nor written over, at the save or the intake', async () => {+ const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);+ mkdirSync(dirname(path), { recursive: true });+ const latin1 = Buffer.from('appearance:\n theme: caf\u00e9\n', 'latin1');+ writeFileSync(path, latin1);+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_USER, 'mcp:\n autoStart: true\n');++ const doc = new Y.Doc();+ doc.getText('source').insert(0, 'appearance:\n theme: dark\n');++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_USER, undefined, fx.ctx)).toMatchObject({+ kind: 'held',+ cause: 'not-utf8',+ path,+ });+ expect(+ await applyExternalConfigChange(doc, CONFIG_DOC_NAME_USER, latin1.toString('utf8'), fx.ctx),+ ).toBe('held');++ expect(readFileSync(path).equals(latin1)).toBe(true);+ expect(doc.getText('source').toString()).toBe('appearance:\n theme: dark\n');+ expect(fx.moved).toEqual([]);+ expect(backupsIn(fx.homedir)).toEqual([]);+ expect(getMetrics().configOutsideChange).toEqual({+ 'store:held-not-utf8': 1,+ 'intake:held-not-utf8': 1,+ });});test('two servers writing the SAME shared file: second store reconciles, first writer wins', async () => {@@ -310,6 +620,14 @@ describe('storeConfigDoc — cross-process reconciliation (file lock)', () => {expect(second.ctx.lkgCache.get(CONFIG_DOC_NAME_USER)).toBe('mcp:\n autoStart: false\n');expect(docB.getText('source').toString()).not.toContain('theme: dark');+ expect(second.moved).toEqual([+ {+ docName: CONFIG_DOC_NAME_USER,+ side: 'ours',+ bytes: 'appearance:\n theme: dark\n',+ fileType: 'config',+ },+ ]);});test('disk matches LKG: writes proceed normally (no spurious reconciliation)', async () => {@@ -338,7 +656,7 @@ describe('storeConfigDoc — cross-process reconciliation (file lock)', () => {expect(existsSync(`${path}.lock`)).toBe(false);});- test('disk diverged but content is INVALID YAML: do NOT reconcile, write our valid content instead', async () => {+ test('disk diverged but content is INVALID YAML: the outside version goes to history, then our valid content is written', async () => {const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);mkdirSync(dirname(path), { recursive: true });writeFileSync(path, 'mcp:\n autoStart: !!!!!!!!!!!!!!\n', 'utf-8');@@ -354,6 +672,52 @@ describe('storeConfigDoc — cross-process reconciliation (file lock)', () => {expect(doc.getText('source').toString()).toBe('appearance:\n theme: dark\n');expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_USER)).toBe('appearance:\n theme: dark\n');expect(fx.rejections).toHaveLength(0);+ expect(fx.moved).toEqual([+ {+ docName: CONFIG_DOC_NAME_USER,+ side: 'theirs',+ bytes: 'mcp:\n autoStart: !!!!!!!!!!!!!!\n',+ fileType: 'config',+ },+ ]);+ expect(getMetrics().configOutsideChange).toEqual({ 'store:invalid-kept-live': 1 });+ });++ test('an invalid outside version that history cannot take goes to the backup folder before our settings are written', async () => {+ const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, 'mcp:\n autoStart: !!!!!!!!!!!!!!\n', 'utf-8');+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_USER, 'mcp:\n autoStart: true\n');+ historySaves = false;++ const doc = new Y.Doc();+ doc.getText('source').insert(0, 'appearance:\n theme: dark\n');++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_USER, undefined, fx.ctx)).toBe('persisted');+ expect(readFileSync(path, 'utf-8')).toBe('appearance:\n theme: dark\n');+ expect(backupsIn(fx.homedir)).toEqual(['mcp:\n autoStart: !!!!!!!!!!!!!!\n']);+ expect(noticed.map(({ side, where }) => ({ side, where }))).toEqual([+ { side: 'theirs', where: 'backup' },+ ]);+ });++ test('an invalid outside version that neither history nor the backup folder can take is not written over', async () => {+ const path = configDocAbsPath(CONFIG_DOC_NAME_USER, fx.ctx);+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, 'mcp:\n autoStart: !!!!!!!!!!!!!!\n', 'utf-8');+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_USER, 'mcp:\n autoStart: true\n');+ historySaves = false;+ blockBackups(fx.homedir);++ const doc = new Y.Doc();+ doc.getText('source').insert(0, 'appearance:\n theme: dark\n');++ expect(await storeConfigDoc(doc, CONFIG_DOC_NAME_USER, undefined, fx.ctx)).toEqual({+ kind: 'held',+ cause: 'no-history-or-backup',+ });+ expect(readFileSync(path, 'utf-8')).toBe('mcp:\n autoStart: !!!!!!!!!!!!!!\n');+ expect(doc.getText('source').toString()).toBe('appearance:\n theme: dark\n');});test('mkdir failure surfaces as write-failed via onConfigRejected; no exception escapes', async () => {@@ -571,6 +935,7 @@ describe('persistence extension dispatch — config-doc integration', () => {const rejections: Array<{ docName: string; error: ConfigValidationError }> = [];const handle = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fx.projectDir,projectDir: fx.projectDir,@@ -592,6 +957,7 @@ describe('persistence extension dispatch — config-doc integration', () => {test('config-doc onStoreDocument validates + writes disk', async () => {const { createPersistenceExtension } = await import('./persistence.ts');const handle = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fx.projectDir,projectDir: fx.projectDir,@@ -618,6 +984,7 @@ describe('persistence extension dispatch — config-doc integration', () => {const notified: string[] = [];const handle = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fx.projectDir,projectDir: fx.projectDir,@@ -649,6 +1016,7 @@ describe('persistence extension dispatch — config-doc integration', () => {const notified: string[] = [];const handle = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fx.projectDir,projectDir: fx.projectDir,@@ -684,6 +1052,7 @@ describe('persistence extension dispatch — config-doc integration', () => {const rejections: Array<{ docName: string; error: ConfigValidationError }> = [];const handle = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fx.projectDir,projectDir: fx.projectDir,@@ -718,6 +1087,7 @@ describe('persistence extension dispatch — config-doc integration', () => {const { createPersistenceExtension } = await import('./persistence.ts');const rejections: Array<{ docName: string; error: ConfigValidationError }> = [];const handle = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fx.projectDir,projectDir: fx.projectDir,@@ -751,7 +1121,7 @@ function readdirSafe(p: string): string[] {}describe('applyExternalConfigChange', () => {- test('valid external content updates Y.Text under CONFIG_FILE_WATCHER_ORIGIN + LKG', () => {+ test('valid external content updates Y.Text under CONFIG_FILE_WATCHER_ORIGIN + LKG', async () => {const doc = new Y.Doc();fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'theme: light\n');doc.getText('source').insert(0, 'theme: light\n');@@ -762,7 +1132,12 @@ describe('applyExternalConfigChange', () => {});const newContent = 'theme: dark\n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, newContent, fx.ctx);+ const outcome = await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ newContent,+ fx.ctx,+ );expect(outcome).toBe('applied');expect(doc.getText('source').toString()).toBe(newContent);@@ -771,7 +1146,86 @@ describe('applyExternalConfigChange', () => {expect(fx.rejections).toHaveLength(0);});- test('content equal to LKG short-circuits: no mutation, no rejection', () => {+ test('a valid outside version applies over an unsaved edit, which goes to history first', async () => {+ const doc = new Y.Doc();+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'mcp:\n autoStart: true\n');+ doc.getText('source').insert(0, 'mcp:\n autoStart: true\n# note\n');++ const outcome = await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ 'mcp:\n autoStart: false\n',+ fx.ctx,+ );++ expect(outcome).toBe('applied');+ expect(doc.getText('source').toString()).toBe('mcp:\n autoStart: false\n');+ expect(fx.moved).toEqual([+ {+ docName: CONFIG_DOC_NAME_PROJECT,+ side: 'ours',+ bytes: 'mcp:\n autoStart: true\n# note\n',+ fileType: 'config',+ },+ ]);+ expect(getMetrics().configOutsideChange).toEqual({ 'intake:applied-displaced': 1 });+ });++ test('a valid outside version with nothing unsaved applies with no history entry', async () => {+ const doc = new Y.Doc();+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'mcp:\n autoStart: true\n');+ doc.getText('source').insert(0, 'mcp:\n autoStart: true\n');++ await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ 'mcp:\n autoStart: false\n',+ fx.ctx,+ );++ expect(doc.getText('source').toString()).toBe('mcp:\n autoStart: false\n');+ expect(fx.moved).toEqual([]);+ expect(getMetrics().configOutsideChange).toEqual({ 'intake:applied': 1 });+ });++ test('when history cannot take the unsaved edit, the backup folder does and the outside version applies', async () => {+ const doc = new Y.Doc();+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'mcp:\n autoStart: true\n');+ doc.getText('source').insert(0, 'mcp:\n autoStart: true\n# note\n');+ historySaves = false;++ expect(+ await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ 'mcp:\n autoStart: false\n',+ fx.ctx,+ ),+ ).toBe('applied');+ expect(doc.getText('source').toString()).toBe('mcp:\n autoStart: false\n');+ expect(backupsIn(fx.homedir)).toEqual(['mcp:\n autoStart: true\n# note\n']);+ });++ test('when neither history nor the backup folder can take the unsaved edit, the outside version is not applied over it', async () => {+ const doc = new Y.Doc();+ fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'mcp:\n autoStart: true\n');+ doc.getText('source').insert(0, 'mcp:\n autoStart: true\n# note\n');+ historySaves = false;+ blockBackups(fx.homedir);++ expect(+ await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT,+ 'mcp:\n autoStart: false\n',+ fx.ctx,+ ),+ ).toBe('held');+ expect(doc.getText('source').toString()).toBe('mcp:\n autoStart: true\n# note\n');+ expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_PROJECT)).toBe('mcp:\n autoStart: true\n');+ });++ test('content equal to LKG short-circuits: no mutation, no rejection', async () => {const doc = new Y.Doc();const yaml = 'mcp:\n autoStart: false\n';fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, yaml);@@ -782,7 +1236,7 @@ describe('applyExternalConfigChange', () => {if (tx.origin === CONFIG_FILE_WATCHER_ORIGIN) mutationCount++;});- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, yaml, fx.ctx);+ const outcome = await applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, yaml, fx.ctx);expect(outcome).toBe('no-op');expect(isConfigEcho(CONFIG_DOC_NAME_PROJECT, yaml, fx.ctx)).toBe(true);@@ -790,8 +1244,8 @@ describe('applyExternalConfigChange', () => {expect(fx.rejections).toHaveLength(0);});- test('null document → no-op (document not loaded yet)', () => {- const outcome = applyExternalConfigChange(+ test('null document → no-op (document not loaded yet)', async () => {+ const outcome = await applyExternalConfigChange(null,CONFIG_DOC_NAME_PROJECT,'theme: dark\n',@@ -805,34 +1259,34 @@ describe('applyExternalConfigChange', () => {test.each(['mcp:\n autoStart: false\n', ''])('distinguishes cached echoes from new content after unloading (%j)',- (content) => {+ async (content) => {const doc = new Y.Doc();- expect(applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, content, fx.ctx)).toBe(+ expect(await applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, content, fx.ctx)).toBe('applied',);doc.destroy();expect(isConfigEcho(CONFIG_DOC_NAME_PROJECT, content, fx.ctx)).toBe(true);- expect(applyExternalConfigChange(null, CONFIG_DOC_NAME_PROJECT, content, fx.ctx)).toBe(+ expect(await applyExternalConfigChange(null, CONFIG_DOC_NAME_PROJECT, content, fx.ctx)).toBe('no-op',);const changed = 'mcp:\n autoStart: true\n';expect(isConfigEcho(CONFIG_DOC_NAME_PROJECT, changed, fx.ctx)).toBe(false);- expect(applyExternalConfigChange(null, CONFIG_DOC_NAME_PROJECT, changed, fx.ctx)).toBe(+ expect(await applyExternalConfigChange(null, CONFIG_DOC_NAME_PROJECT, changed, fx.ctx)).toBe('no-op',);expect(isConfigEcho(CONFIG_DOC_NAME_PROJECT, changed, fx.ctx)).toBe(false);},);- test('YAML parse error → rejected; Y.Text NOT mutated; onConfigRejected fired', () => {+ test('YAML parse error → rejected; Y.Text NOT mutated; onConfigRejected fired', async () => {const doc = new Y.Doc();const valid = 'theme: light\n';fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, valid);doc.getText('source').insert(0, valid);const broken = 'theme: !!!!!\n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, broken, fx.ctx);+ const outcome = await applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, broken, fx.ctx);expect(outcome).toBe('rejected');expect(doc.getText('source').toString()).toBe(valid);@@ -846,12 +1300,12 @@ describe('applyExternalConfigChange', () => {expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_PROJECT)).toBe(valid);});- test('schema-invalid external content → rejected with structured issues', () => {+ test('schema-invalid external content → rejected with structured issues', async () => {const doc = new Y.Doc();fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'content:\n dir: docs\n');const invalid = 'appearance:\n theme: midnight\n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, invalid, fx.ctx);+ const outcome = await applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, invalid, fx.ctx);expect(outcome).toBe('rejected');expect(fx.rejections).toHaveLength(1);@@ -865,24 +1319,29 @@ describe('applyExternalConfigChange', () => {}});- test('LKG-undefined + valid external content → applied; LKG seeded', () => {+ test('LKG-undefined + valid external content → applied; LKG seeded', async () => {const doc = new Y.Doc();expect(fx.ctx.lkgCache.has(CONFIG_DOC_NAME_USER)).toBe(false);const yaml = 'theme: dark\n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_USER, yaml, fx.ctx);+ const outcome = await applyExternalConfigChange(doc, CONFIG_DOC_NAME_USER, yaml, fx.ctx);expect(outcome).toBe('applied');expect(doc.getText('source').toString()).toBe(yaml);expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_USER)).toBe(yaml);});- test('project-local: external content propagates to Y.Text + LKG', () => {+ test('project-local: external content propagates to Y.Text + LKG', async () => {const doc = new Y.Doc();expect(fx.ctx.lkgCache.has(CONFIG_DOC_NAME_PROJECT_LOCAL)).toBe(false);const yaml = 'autoSync:\n enabled: true\n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT_LOCAL, yaml, fx.ctx);+ const outcome = await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_PROJECT_LOCAL,+ yaml,+ fx.ctx,+ );expect(outcome).toBe('applied');expect(doc.getText('source').toString()).toBe(yaml);@@ -894,7 +1353,7 @@ describe('applyExternalConfigChange', () => {fx.ctx.lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'theme: light\n');doc.getText('source').insert(0, 'theme: light\n');- applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, 'theme: dark\n', fx.ctx);+ await applyExternalConfigChange(doc, CONFIG_DOC_NAME_PROJECT, 'theme: dark\n', fx.ctx);const outcome = await storeConfigDoc(doc,@@ -1123,7 +1582,7 @@ describe('okignore — storeConfigDoc validator', () => {});describe('okignore — applyExternalConfigChange', () => {- test('valid external content updates Y.Text under CONFIG_FILE_WATCHER_ORIGIN', () => {+ test('valid external content updates Y.Text under CONFIG_FILE_WATCHER_ORIGIN', async () => {const doc = new Y.Doc();fx.ctx.lkgCache.set(CONFIG_DOC_NAME_OKIGNORE, '');@@ -1133,7 +1592,12 @@ describe('okignore — applyExternalConfigChange', () => {});const newContent = 'drafts/\n*.tmp\n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, newContent, fx.ctx);+ const outcome = await applyExternalConfigChange(+ doc,+ CONFIG_DOC_NAME_OKIGNORE,+ newContent,+ fx.ctx,+ );expect(outcome).toBe('applied');expect(doc.getText('source').toString()).toBe(newContent);@@ -1142,14 +1606,14 @@ describe('okignore — applyExternalConfigChange', () => {expect(fx.rejections).toHaveLength(0);});- test('invalid external content (whitespace-only line) → rejected; Y.Text NOT mutated', () => {+ test('invalid external content (whitespace-only line) → rejected; Y.Text NOT mutated', async () => {const doc = new Y.Doc();const valid = 'drafts/\n';fx.ctx.lkgCache.set(CONFIG_DOC_NAME_OKIGNORE, valid);doc.getText('source').insert(0, valid);const broken = 'drafts/\n \n';- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, broken, fx.ctx);+ const outcome = await applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, broken, fx.ctx);expect(outcome).toBe('rejected');expect(doc.getText('source').toString()).toBe(valid);@@ -1164,7 +1628,7 @@ describe('okignore — applyExternalConfigChange', () => {expect(fx.ctx.lkgCache.get(CONFIG_DOC_NAME_OKIGNORE)).toBe(valid);});- test('content equal to LKG short-circuits: no rejection, no Y.Text mutation', () => {+ test('content equal to LKG short-circuits: no rejection, no Y.Text mutation', async () => {const doc = new Y.Doc();const body = 'drafts/\n';fx.ctx.lkgCache.set(CONFIG_DOC_NAME_OKIGNORE, body);@@ -1175,7 +1639,7 @@ describe('okignore — applyExternalConfigChange', () => {if (tx.origin === CONFIG_FILE_WATCHER_ORIGIN) mutationCount++;});- const outcome = applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, body, fx.ctx);+ const outcome = await applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, body, fx.ctx);expect(outcome).toBe('no-op');expect(mutationCount).toBe(0);@@ -1246,7 +1710,7 @@ describe('okignore — rejection counter telemetry', () => {const doc = new Y.Doc();fx.ctx.lkgCache.set(CONFIG_DOC_NAME_OKIGNORE, 'drafts/\n');- applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, ' \n', fx.ctx);+ await applyExternalConfigChange(doc, CONFIG_DOC_NAME_OKIGNORE, ' \n', fx.ctx);const points = await readPoints('ok.config.ignore.rejection_total');const total = points.reduce((acc, p) => acc + p.value, 0);diff --git a/packages/server/src/config-persistence.ts b/packages/server/src/config-persistence.tsindex 050b27429..c5d61b3ff 100644--- a/packages/server/src/config-persistence.ts+++ b/packages/server/src/config-persistence.ts@@ -1,5 +1,6 @@import { existsSync, readFileSync } from 'node:fs';-import { dirname, resolve } from 'node:path';+import { homedir } from 'node:os';+import { basename, dirname, resolve } from 'node:path';import {addConfigSpanEvent,CONFIG_DOC_NAME_OKIGNORE,@@ -27,8 +28,18 @@ import {CONFIG_FILE_WATCHER_ORIGIN,CONFIG_VALIDATION_REVERT_ORIGIN,} from './config-edit-origin.ts';+import type { FileObservation } from './disk-receipts.ts';import { tracedMkdir, tracedRename, tracedUnlinkSync, tracedWriteFile } from './fs-traced.ts';import { getLogger } from './logger.ts';+import { type KeptCopy, keepNoEngineVersion, type MergeHistoryRecorder } from './merge-history.ts';+import { incrementConfigOutsideChange, incrementStoreRestatRefused } from './metrics.ts';+import { heldFor, heldNotUtf8, type SaveHold } from './save-hold.ts';+import {+ readObservedText,+ restatFile,+ StoreRestatFailedError,+ StoreRestatRefusedError,+} from './store-compare.ts';import { getMeter } from './telemetry.ts';const log = getLogger('config-persistence');@@ -71,6 +82,98 @@ export interface ConfigPersistenceCtx {homedirOverride?: string;onConfigRejected?: (docName: string, error: ConfigValidationError) => void;ephemeral?: boolean;+ agreedDisk: Map<string, string>;+ history: Pick<MergeHistoryRecorder, 'saveNoEngine' | 'noticeNoEngine'> | null;+}++const MAX_CONFIG_ROUNDS = 3;++function keepConfigVersion(+ documentName: string,+ side: 'ours' | 'theirs',+ bytes: string,+ ctx: ConfigPersistenceCtx,+): Promise<KeptCopy | null> {+ return keepNoEngineVersion(+ ctx.history,+ ctx.homedirOverride ?? homedir(),+ ctx.contentDir ?? ctx.projectDir,+ documentName,+ { side, bytes },+ 'config',+ basename(configDocAbsPath(documentName, ctx)),+ );+}++function agreedOf(documentName: string, ctx: ConfigPersistenceCtx): string | undefined {+ return ctx.agreedDisk.get(documentName) ?? ctx.lkgCache.get(documentName);+}++function agreeWithDisk(documentName: string, content: string, ctx: ConfigPersistenceCtx): void {+ ctx.lkgCache.set(documentName, content);+ ctx.agreedDisk.set(documentName, content);+}++function holdsUnsavedEdit(+ documentName: string,+ live: string,+ outside: string,+ ctx: ConfigPersistenceCtx,+): boolean {+ if (live.length === 0 && documentName !== CONFIG_DOC_NAME_OKIGNORE) return false;+ return (+ live !== outside &&+ live !== agreedOf(documentName, ctx) &&+ live !== ctx.lkgCache.get(documentName)+ );+}++async function saveDisplacedEdits(+ document: Y.Doc,+ documentName: string,+ outside: string,+ ctx: ConfigPersistenceCtx,+): Promise<KeptCopy[] | 'held' | 'deferred'> {+ const ytext = document.getText('source');+ const copies: KeptCopy[] = [];+ for (let attempt = 0; attempt < MAX_CONFIG_ROUNDS; attempt++) {+ const live = ytext.toString();+ if (!holdsUnsavedEdit(documentName, live, outside, ctx)) return copies;+ const copy = await keepConfigVersion(documentName, 'ours', live, ctx);+ if (copy === null) return 'held';+ copies.push(copy);+ if (ytext.toString() === live) return copies;+ }+ return 'deferred';+}++function noticeDisplacedEdits(+ documentName: string,+ copies: readonly KeptCopy[],+ ctx: ConfigPersistenceCtx,+): void {+ for (const copy of copies) ctx.history?.noticeNoEngine(documentName, 'ours', 'config', copy);+}++function outsideDecoding(+ documentName: string,+ content: string,+ ctx: ConfigPersistenceCtx,+): 'lossless' | 'moved-on' | 'not-utf8' {+ if (!content.includes('\uFFFD')) return 'lossless';+ const read = readObservedText(configDocAbsPath(documentName, ctx));+ if (read.kind !== 'read' || read.text !== content) return 'moved-on';+ return read.lossless ? 'lossless' : 'not-utf8';+}++const intakeChains = new WeakMap<Map<string, string>, Map<string, Promise<unknown>>>();++function replaceLiveConfig(document: Y.Doc, content: string): void {+ const ytext = document.getText('source');+ document.transact(() => {+ if (ytext.length > 0) ytext.delete(0, ytext.length);+ ytext.insert(0, content);+ }, CONFIG_FILE_WATCHER_ORIGIN);}export function configDocAbsPath(documentName: string, ctx: ConfigPersistenceCtx): string {@@ -208,13 +311,21 @@ export function loadConfigDoc(} else {ctx.lkgCache.set(documentName, defaultLkgFor(documentName));}+ ctx.agreedDisk.set(documentName, raw);}-async function atomicWriteConfig(absPath: string, content: string): Promise<void> {+async function atomicWriteConfig(+ absPath: string,+ content: string,+ observation: FileObservation | null,+): Promise<void> {await tracedMkdir(dirname(absPath), { recursive: true });const tmpPath = atomicTempPath(absPath);try {await tracedWriteFile(tmpPath, content, 'utf-8');+ const restat = restatFile(absPath, observation);+ if (restat.kind === 'failed') throw new StoreRestatFailedError(absPath, restat.error);+ if (restat.kind === 'moved') throw new StoreRestatRefusedError(absPath);await tracedRename(tmpPath, absPath);} catch (e) {try {@@ -224,7 +335,13 @@ async function atomicWriteConfig(absPath: string, content: string): Promise<void}}-type StoreConfigDocOutcome = 'persisted' | 'reverted' | 'write-failed' | 'no-op' | 'reconciled';+export type StoreConfigDocOutcome =+ | 'persisted'+ | 'reverted'+ | 'write-failed'+ | 'no-op'+ | 'reconciled'+ | SaveHold;export async function storeConfigDoc(document: Y.Doc,@@ -245,7 +362,7 @@ export async function storeConfigDoc(function persistOutcomeAttr(outcome: StoreConfigDocOutcome): 'success' | 'reverted' | 'rejected' {if (outcome === 'reverted') return 'reverted';- if (outcome === 'write-failed') return 'rejected';+ if (outcome === 'write-failed' || typeof outcome === 'object') return 'rejected';return 'success';}@@ -325,15 +442,38 @@ async function storeConfigDocInner(return await withFileLock(`${filePath}.lock`,async () => {- let diskContent: string | null = null;- try {- diskContent = readFileSync(filePath, 'utf-8');- } catch (e) {- const code = (e as NodeJS.ErrnoException).code;- if (code !== 'ENOENT') {- const detail = e instanceof Error ? e.message : String(e);+ const writeFailed = (e: unknown, detail: string): StoreConfigDocOutcome => {+ log.warn(+ { docName: documentName, path: filePath, err: e },+ `[config-persistence] write-failed at ${filePath}: ${detail}`,+ );+ ctx.onConfigRejected?.(documentName, {+ code: 'WRITE_ERROR',+ detail: `Failed to persist config at ${filePath}: ${detail}`,+ });+ return 'write-failed';+ };+ const writeOurs = async (+ observation: FileObservation | null,+ ): Promise<'written' | 'moved' | StoreConfigDocOutcome> => {+ try {+ await atomicWriteConfig(filePath, content, observation);+ return 'written';+ } catch (e) {+ if (e instanceof StoreRestatRefusedError) {+ incrementStoreRestatRefused();+ return 'moved';+ }+ return writeFailed(e, e instanceof Error ? e.message : String(e));+ }+ };++ for (let round = 0; round < MAX_CONFIG_ROUNDS; round++) {+ const read = readObservedText(filePath);+ if (read.kind === 'failed') {+ const detail = read.error instanceof Error ? read.error.message : String(read.error);log.warn(- { docName: documentName, path: filePath, err: e },+ { docName: documentName, path: filePath, err: read.error },`[config-persistence] could not read config for reconciliation: ${detail}`,);ctx.onConfigRejected?.(documentName, {@@ -342,44 +482,90 @@ async function storeConfigDocInner(});return 'write-failed';}- }-- if (diskContent !== null && lkg !== undefined && diskContent !== lkg) {- const diskValidation = validateConfigContent(documentName, diskContent);- if (diskValidation.ok) {- document.transact(() => {- if (ytext.length > 0) ytext.delete(0, ytext.length);- ytext.insert(0, diskContent);- }, CONFIG_FILE_WATCHER_ORIGIN);- ctx.lkgCache.set(documentName, diskContent);- log.info(- { docName: documentName, path: filePath },- '[config-persistence] reconciled: external writer landed; imported disk into Y.Text',+ const diskContent = read.kind === 'read' ? read.text : null;+ const agreed = agreedOf(documentName, ctx);++ if (diskContent !== null && agreed !== undefined && diskContent !== agreed) {+ if (read.kind === 'read' && !read.lossless) {+ incrementConfigOutsideChange('store', 'held-not-utf8');+ log.info(+ { docName: documentName, path: filePath },+ '[config-persistence] the file changed outside to bytes that are not valid UTF-8; nothing was applied or written',+ );+ return heldNotUtf8(filePath, read.observation);+ }+ const diskValidation = validateConfigContent(documentName, diskContent);+ if (diskValidation.ok) {+ const displaced = await saveDisplacedEdits(document, documentName, diskContent, ctx);+ if (displaced === 'held') {+ incrementConfigOutsideChange('store', 'held-no-history-or-backup');+ log.warn(+ { docName: documentName, path: filePath },+ '[config-persistence] a valid outside version landed but the unsaved edit could not be kept in history or the backup folder; nothing was applied or written',+ );+ return heldFor('no-history-or-backup');+ }+ if (displaced === 'deferred') {+ incrementConfigOutsideChange('store', 'deferred');+ log.warn(+ { docName: documentName, path: filePath },+ '[config-persistence] a valid outside version landed while the settings kept changing here; it was not applied, and the edits displaced so far were kept in history or the backup folder',+ );+ return heldFor('edits-changing');+ }+ if (displaced.length > 0) {+ const again = readObservedText(filePath);+ if (again.kind !== 'read' || again.text !== diskContent) continue;+ }+ replaceLiveConfig(document, diskContent);+ agreeWithDisk(documentName, diskContent, ctx);+ noticeDisplacedEdits(documentName, displaced, ctx);+ incrementConfigOutsideChange(+ 'store',+ displaced.length > 0 ? 'applied-displaced' : 'applied',+ );+ log.info(+ { docName: documentName, path: filePath },+ '[config-persistence] reconciled: external writer landed; imported disk into Y.Text',+ );+ return 'reconciled';+ }+ const copy = await keepConfigVersion(documentName, 'theirs', diskContent, ctx);+ if (copy === null) {+ incrementConfigOutsideChange('store', 'held-no-history-or-backup');+ log.warn(+ { docName: documentName, path: filePath },+ '[config-persistence] an invalid outside version landed and could not be kept in history or the backup folder; it was not written over',+ );+ return heldFor('no-history-or-backup');+ }+ const again = readObservedText(filePath);+ if (again.kind !== 'read' || again.text !== diskContent) continue;+ const written = await writeOurs(again.observation);+ if (written === 'moved') continue;+ if (written !== 'written') return written;+ agreeWithDisk(documentName, content, ctx);+ ctx.history?.noticeNoEngine(documentName, 'theirs', 'config', copy);+ incrementConfigOutsideChange('store', 'invalid-kept-live');+ log.warn(+ { docName: documentName, path: filePath, keptIn: copy.where },+ '[config-persistence] disk diverged from LKG but contains invalid content; it was kept in history or the backup folder and the local write landed',);- return 'reconciled';+ return 'persisted';}- log.warn(- { docName: documentName, path: filePath },- '[config-persistence] disk diverged from LKG but contains invalid content; proceeding with local write',- );- }- try {- await atomicWriteConfig(filePath, content);- } catch (e) {- const detail = e instanceof Error ? e.message : String(e);- log.warn(- { docName: documentName, path: filePath, err: e },- `[config-persistence] write-failed at ${filePath}: ${detail}`,- );- ctx.onConfigRejected?.(documentName, {- code: 'WRITE_ERROR',- detail: `Failed to persist config at ${filePath}: ${detail}`,- });- return 'write-failed';+ const written = await writeOurs(read.kind === 'read' ? read.observation : null);+ if (written === 'moved') continue;+ if (written !== 'written') return written;+ agreeWithDisk(documentName, content, ctx);+ return 'persisted';}- ctx.lkgCache.set(documentName, content);- return 'persisted';+ incrementConfigOutsideChange('store', 'held-exhausted');+ log.warn(+ { docName: documentName, path: filePath, rounds: MAX_CONFIG_ROUNDS },+ '[config-persistence] the file kept changing outside while it was being saved; nothing more was written',+ );+ return heldFor('keeps-changing');},{onWarn: (message, context) => {@@ -414,6 +600,7 @@ export function resetConfigDocForTest(if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;}ctx.lkgCache.delete(documentName);+ ctx.agreedDisk.delete(documentName);if (document === null) return;const ytext = document.getText('source');if (ytext.length > 0) {@@ -424,14 +611,14 @@ export function resetConfigDocForTest(loadConfigDoc(document, documentName, ctx);}-type ApplyExternalConfigChangeOutcome = 'applied' | 'rejected' | 'no-op';+type ApplyExternalConfigChangeOutcome = 'applied' | 'rejected' | 'no-op' | 'held';export function isConfigEcho(documentName: string,content: string,ctx: ConfigPersistenceCtx,): boolean {- return ctx.lkgCache.get(documentName) === content;+ return ctx.lkgCache.get(documentName) === content || ctx.agreedDisk.get(documentName) === content;}export function applyExternalConfigChange(@@ -439,11 +626,43 @@ export function applyExternalConfigChange(documentName: string,content: string,ctx: ConfigPersistenceCtx,-): ApplyExternalConfigChangeOutcome {+): Promise<ApplyExternalConfigChangeOutcome> {+ let chains = intakeChains.get(ctx.lkgCache);+ if (chains === undefined) {+ chains = new Map();+ intakeChains.set(ctx.lkgCache, chains);+ }+ const previous = chains.get(documentName) ?? Promise.resolve();+ const run = previous.then(() => takeInConfigChange(document, documentName, content, ctx));+ const settled = run.catch(() => {});+ chains.set(documentName, settled);+ void settled.then(() => {+ if (chains.get(documentName) === settled) chains.delete(documentName);+ });+ return run;+}++async function takeInConfigChange(+ document: Y.Doc | null,+ documentName: string,+ content: string,+ ctx: ConfigPersistenceCtx,+): Promise<ApplyExternalConfigChangeOutcome> {if (!document) return 'no-op';if (isConfigEcho(documentName, content, ctx)) return 'no-op';+ const decoded = outsideDecoding(documentName, content, ctx);+ if (decoded === 'moved-on') return 'no-op';+ if (decoded === 'not-utf8') {+ incrementConfigOutsideChange('intake', 'held-not-utf8');+ log.warn(+ { docName: documentName },+ '[config-persistence] the file changed outside to bytes that are not valid UTF-8; nothing was applied',+ );+ return 'held';+ }+const scope = configScopeAttr(documentName);const validation = withConfigSpanSync('config.validate',@@ -460,15 +679,31 @@ export function applyExternalConfigChange(okignoreRejectionCounter().add(1, { 'error.code': validation.error.code });}ctx.onConfigRejected?.(documentName, validation.error);+ incrementConfigOutsideChange('intake', 'rejected');return 'rejected';}- const ytext = document.getText('source');- document.transact(() => {- if (ytext.length > 0) ytext.delete(0, ytext.length);- ytext.insert(0, content);- }, CONFIG_FILE_WATCHER_ORIGIN);+ const displaced = await saveDisplacedEdits(document, documentName, content, ctx);+ if (displaced === 'held') {+ incrementConfigOutsideChange('intake', 'held-no-history-or-backup');+ log.warn(+ { docName: documentName },+ '[config-persistence] a valid outside version landed but the unsaved edit could not be kept in history or the backup folder; it was not applied',+ );+ return 'held';+ }+ if (displaced === 'deferred') {+ incrementConfigOutsideChange('intake', 'deferred');+ log.warn(+ { docName: documentName },+ '[config-persistence] a valid outside version landed while the settings kept changing here; it was not applied, and the edits displaced so far were kept in history or the backup folder',+ );+ return 'held';+ }- ctx.lkgCache.set(documentName, content);+ replaceLiveConfig(document, content);+ agreeWithDisk(documentName, content, ctx);+ noticeDisplacedEdits(documentName, displaced, ctx);+ incrementConfigOutsideChange('intake', displaced.length > 0 ? 'applied-displaced' : 'applied');return 'applied';}diff --git a/packages/server/src/config-telemetry.test.ts b/packages/server/src/config-telemetry.test.tsindex c1cb7f52e..91bce1eef 100644--- a/packages/server/src/config-telemetry.test.ts+++ b/packages/server/src/config-telemetry.test.ts@@ -217,7 +217,12 @@ describe('config-edit OTel spans', () => {const ytext = ydoc.getText('source');ytext.insert(0, 'mcp:\n tools:\n search:\n maxResults: 75\n');const lkgCache = new Map<string, string>();- const ctx = { projectDir: testDir, lkgCache };+ const ctx = {+ projectDir: testDir,+ lkgCache,+ agreedDisk: new Map<string, string>(),+ history: null,+ };const outcome = await storeConfigDoc(ydoc, CONFIG_DOC_NAME_PROJECT, undefined, ctx);expect(outcome).toBe('persisted');@@ -242,6 +247,8 @@ describe('config-edit OTel spans', () => {projectDir: testDir,lkgCache,onConfigRejected: () => {},+ agreedDisk: new Map<string, string>(),+ history: null,};const outcome = await storeConfigDoc(ydoc, CONFIG_DOC_NAME_PROJECT, undefined, ctx);@@ -260,13 +267,18 @@ describe('config-edit OTel spans', () => {});describe('applyExternalConfigChange — file watcher path', () => {- it('emits config.validate(L3) on a watcher-driven change', () => {+ it('emits config.validate(L3) on a watcher-driven change', async () => {const ydoc = new Y.Doc();const lkgCache = new Map<string, string>();lkgCache.set(CONFIG_DOC_NAME_PROJECT, 'mcp:\n autoStart: false\n');- const ctx = { projectDir: testDir, lkgCache };+ const ctx = {+ projectDir: testDir,+ lkgCache,+ agreedDisk: new Map<string, string>(),+ history: null,+ };- const outcome = applyExternalConfigChange(+ const outcome = await applyExternalConfigChange(ydoc,CONFIG_DOC_NAME_PROJECT,'mcp:\n autoStart: true\n',diff --git a/packages/server/src/disk-receipts.test.ts b/packages/server/src/disk-receipts.test.tsindex b4e4502ef..7e622c88f 100644--- a/packages/server/src/disk-receipts.test.ts+++ b/packages/server/src/disk-receipts.test.ts@@ -11,7 +11,7 @@ import {import { tmpdir } from 'node:os';import { join } from 'node:path';import { afterEach, beforeEach, describe, expect, test } from 'vitest';-import { DiskReceiptLog } from './disk-receipts.ts';+import { DiskReceiptLog, receiptFileIsGoneIn } from './disk-receipts.ts';import { getMetrics, resetMetrics } from './metrics.ts';import { contentHash } from './version-hash.ts';@@ -174,6 +174,24 @@ describe('DiskReceiptLog', () => {expect(log.isRecentOwnWrite('doc', contentHash('v9\n'))).toBe(false);});+ test('a receipt counts as gone only when no file the document could live in exists', () => {+ const content = join(dir, 'content');+ mkdirSync(join(content, 'diagrams'), { recursive: true });+ writeFileSync(join(content, 'notes.md'), '# Notes\n');+ writeFileSync(join(content, 'diagrams', 'flow.mmd'), 'graph TD\n');+ writeFileSync(join(content, 'value.ts'), 'export {};\n');+ const isGone = receiptFileIsGoneIn(content);++ expect(isGone('notes')).toBe(false);+ expect(isGone('diagrams/flow.mmd')).toBe(false);+ expect(isGone('value.ts')).toBe(false);+ expect(isGone('gone')).toBe(true);+ expect(isGone('diagrams/gone.mmd')).toBe(true);+ expect(isGone('__skill__/global/demo')).toBe(false);+ expect(isGone('__config__/project')).toBe(false);+ expect(isGone('../outside')).toBe(false);+ });+test('pruning drops receipts whose file is gone and rewrites the log without them', () => {const log = new DiskReceiptLog({ path });log.recordAgreed('present', 'a\n');diff --git a/packages/server/src/disk-receipts.ts b/packages/server/src/disk-receipts.tsindex c5a2a769a..0c4436f70 100644--- a/packages/server/src/disk-receipts.ts+++ b/packages/server/src/disk-receipts.ts@@ -1,5 +1,14 @@import { closeSync, constants, existsSync, lstatSync, openSync, readFileSync } from 'node:fs';-import { dirname } from 'node:path';+import { dirname, resolve } from 'node:path';+import {+ CONFIG_DOC_NAMES,+ isEditableTextDocFile,+ isExcalidrawDocFile,+ isManagedArtifactDocName,+ isMermaidDocFile,+ SUPPORTED_DOC_EXTENSIONS,+ SYSTEM_DOC_NAME,+} from '@inkeep/open-knowledge-core';import { atomicTempPath } from '@inkeep/open-knowledge-core/server';import {tracedAppendNoFollowSync,@@ -16,6 +25,7 @@ import {incrementReceiptRecordsOtherVersion,incrementReceiptRecordsUnreadable,} from './metrics.ts';+import { isWithinDir } from './path-utils.ts';import { contentHash } from './version-hash.ts';const DISK_RECEIPT_SCHEMA_VERSION = 1;@@ -108,6 +118,39 @@ function parseLine(line: string): ParsedLine {};}+function isReservedReceiptName(docName: string): boolean {+ return (+ docName === SYSTEM_DOC_NAME ||+ (CONFIG_DOC_NAMES as readonly string[]).includes(docName) ||+ isManagedArtifactDocName(docName)+ );+}++function receiptFileCandidates(docName: string): string[] {+ const markdown = SUPPORTED_DOC_EXTENSIONS.map((extension) => `${docName}${extension}`);+ const ownPath =+ isMermaidDocFile(docName) || isExcalidrawDocFile(docName) || isEditableTextDocFile(docName);+ return ownPath ? [docName, ...markdown] : markdown;+}++export function receiptFileIsGoneIn(contentDir: string): (docName: string) => boolean {+ return (docName) => {+ if (isReservedReceiptName(docName)) return false;+ for (const relativePath of receiptFileCandidates(docName)) {+ const candidate = resolve(contentDir, relativePath);+ if (!isWithinDir(candidate, contentDir)) return false;+ try {+ lstatSync(candidate);+ return false;+ } catch (err) {+ const code = errnoCode(err);+ if (code !== 'ENOENT' && code !== 'ENOTDIR') return false;+ }+ }+ return true;+ };+}+function sameObservation(receipt: DiskReceipt, observation: FileObservation): boolean {return (receipt.size === Number(observation.size) &&diff --git a/packages/server/src/display-path.ts b/packages/server/src/display-path.tsnew file mode 100644index 000000000..83a6053bd--- /dev/null+++ b/packages/server/src/display-path.ts@@ -0,0 +1,9 @@+import { relative } from 'node:path';+import { isWithinDir, toPosix } from './path-utils.ts';++export function displayPathFor(abs: string, projectDir: string | null, home: string): string {+ if (projectDir !== null && isWithinDir(abs, projectDir))+ return toPosix(relative(projectDir, abs));+ if (isWithinDir(abs, home)) return `~/${toPosix(relative(home, abs))}`;+ return toPosix(abs);+}diff --git a/packages/server/src/doc-notices.test.ts b/packages/server/src/doc-notices.test.tsindex 0c1325451..ad1466020 100644--- a/packages/server/src/doc-notices.test.ts+++ b/packages/server/src/doc-notices.test.ts@@ -6,7 +6,12 @@ import simpleGit from 'simple-git';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';import { _resetDocExtensionsForTests, registerDocExtension } from './doc-extensions.ts';-import { DocNoticeLedger, docNoticesPath, NOTICE_WITHDRAW_AFTER_MS } from './doc-notices.ts';+import {+ DocNoticeLedger,+ docNoticesPath,+ NOTICE_WITHDRAW_AFTER_MS,+ type NoticeFile,+} from './doc-notices.ts';import { createMergeHistoryRecorder } from './merge-history.ts';import {DEFAULT_CHECKPOINT_RETENTION,@@ -42,7 +47,14 @@ describe('DocNoticeLedger', () => {writeFileSync(file, '# Doc\n');}- function ledger(options: { shadow?: ShadowHandle; ready?: boolean } = {}): DocNoticeLedger {+ function ledger(+ options: {+ shadow?: ShadowHandle;+ ready?: boolean;+ resolveFile?: (docName: string) => NoticeFile | null;+ isSaveHeld?: (docName: string) => boolean;+ } = {},+ ): DocNoticeLedger {return new DocNoticeLedger({projectDir,contentDir: projectDir,@@ -51,6 +63,8 @@ describe('DocNoticeLedger', () => {signal,isHeld: (docName) => held.has(docName),now: () => clock,+ resolveFile: options.resolveFile,+ isSaveHeld: options.isSaveHeld,});}@@ -113,6 +127,107 @@ describe('DocNoticeLedger', () => {expect(fresh).not.toBe(id);});+ test('backup and held-save notices survive a restart, and withdrawing a held save leaves any other notice alone', async () => {+ seedDoc('flow', '.mmd');+ seedDoc('notes');+ const backup = '~/.ok/edit-backups/discarded/flow.mmd/2026-10-21T10-00-00-000Z.mmd';+ ledger().record('flow.mmd', 'main', {+ kind: 'moved-to-backup',+ side: 'theirs',+ reason: 'no-merge-engine',+ backup,+ });+ ledger().record('notes', 'main', { kind: 'save-held', cause: 'keeps-changing' });++ const reopened = ledger();+ expect(await reopened.list('main')).toEqual([+ expect.objectContaining({ docName: 'notes', kind: 'save-held', cause: 'keeps-changing' }),+ expect.objectContaining({+ docName: 'flow.mmd',+ file: 'flow.mmd',+ kind: 'moved-to-backup',+ side: 'theirs',+ reason: 'no-merge-engine',+ backup,+ entries: [],+ }),+ ]);++ reopened.withdrawHeld('flow.mmd', 'main');+ reopened.withdrawHeld('notes', 'main');+ expect((await ledger().list('main')).map((notice) => notice.docName)).toEqual(['flow.mmd']);+ });++ test('a held save and a kept version on one document show side by side, and clearing the hold keeps the kept-version notice', async () => {+ seedDoc('notes');+ const kept = ledger().record('notes', 'main', { kind: 'both-kept', kept: KEPT_ONE });+ const held = ledger().record('notes', 'main', { kind: 'save-held', cause: 'unreadable' });+ ledger().record('notes', 'main', {+ kind: 'moved-to-history',+ side: 'theirs',+ reason: 'check-failed',+ entry: 'a'.repeat(40),+ });++ const shown = await ledger().list('main');+ expect(shown.map((notice) => notice.kind).sort()).toEqual(['moved-to-history', 'save-held']);+ expect(shown.find((notice) => notice.kind === 'save-held')?.id).toBe(held);+ expect(shown.find((notice) => notice.kind === 'moved-to-history')?.id).toBe(kept);++ const reopened = ledger();+ reopened.rename('notes', 'renamed', 'main');+ reopened.withdrawHeld('renamed', 'main');++ expect(await ledger().list('main')).toEqual([+ expect.objectContaining({+ docName: 'renamed',+ kind: 'moved-to-history',+ entries: ['a'.repeat(40)],+ }),+ ]);+ });++ test('a held-save notice whose hold is gone, as after a restart, is withdrawn at the next read and the kept-version notice stays', async () => {+ seedDoc('notes');+ ledger().record('notes', 'main', { kind: 'both-kept', kept: KEPT_ONE });+ ledger().record('notes', 'main', { kind: 'save-held', cause: 'keeps-changing' });++ expect(+ (await ledger({ isSaveHeld: () => true }).list('main')).map((notice) => notice.kind).sort(),+ ).toEqual(['both-kept', 'save-held']);+ expect(+ (await ledger({ ready: false, isSaveHeld: () => false }).list('main')).map(+ (notice) => notice.kind,+ ),+ ).toContain('save-held');++ const afterRestart = ledger({ isSaveHeld: () => false });+ expect((await afterRestart.list('main')).map((notice) => notice.kind)).toEqual(['both-kept']);+ expect((await ledger().list('main')).map((notice) => notice.kind)).toEqual(['both-kept']);+ });++ test('a dismissed held-save notice comes back when the hold is raised again, and a hold raised again while shown changes nothing', async () => {+ seedDoc('notes');+ const notices = ledger({ isSaveHeld: () => true });+ const first = notices.record('notes', 'main', { kind: 'save-held', cause: 'unreadable' });+ signal.mockClear();++ expect(notices.record('notes', 'main', { kind: 'save-held', cause: 'unreadable' })).toBe(first);+ expect(signal).not.toHaveBeenCalled();+ expect(await notices.list('main')).toEqual([+ expect.objectContaining({ id: first, kind: 'save-held', events: 1 }),+ ]);++ expect(notices.dismiss('notes', first ?? '')).toBe(true);+ expect(await notices.list('main')).toEqual([]);++ const again = notices.record('notes', 'main', { kind: 'save-held', cause: 'unreadable' });+ expect(again).not.toBe(first);+ expect(await notices.list('main')).toEqual([+ expect.objectContaining({ id: again, kind: 'save-held', cause: 'unreadable' }),+ ]);+ });+test('a notice file from another version, or one it cannot parse, is dropped and the project still opens', async () => {seedDoc('notes');ledger().record('notes', 'main', { kind: 'both-kept', kept: KEPT_ONE });@@ -129,14 +244,63 @@ describe('DocNoticeLedger', () => {}});- test('the system document and config documents never get a notice', async () => {+ test('the system document never gets a notice', async () => {const notices = ledger();expect(notices.record('__system__', 'main', { kind: 'both-kept', kept: KEPT_ONE })).toBeNull();+ expect(signal).not.toHaveBeenCalled();+ });++ test('a settings file gets a notice named after its file, and dismissing it removes it', async () => {+ const outside = join(projectDir, 'outside');+ const files = new Map<string, NoticeFile>();for (const configDoc of CONFIG_DOC_NAMES) {- expect(notices.record(configDoc, 'main', { kind: 'both-kept', kept: KEPT_ONE })).toBeNull();+ const abs = join(outside, configDoc.replace(/\//g, '-'));+ mkdirSync(dirname(abs), { recursive: true });+ writeFileSync(abs, 'a: 1\n');+ files.set(configDoc, { abs, display: `.ok/${configDoc.replace(/\//g, '-')}` });}- expect(signal).not.toHaveBeenCalled();+ const notices = ledger({ resolveFile: (docName) => files.get(docName) ?? null });+ const ids = CONFIG_DOC_NAMES.map((configDoc) =>+ notices.record(configDoc, 'main', {+ kind: 'moved-to-history',+ side: 'ours',+ reason: 'outside-settings-applied',+ entry: 'e'.repeat(40),+ }),+ );++ clock += NOTICE_WITHDRAW_AFTER_MS * 2;+ const listed = await notices.list('main');+ expect(listed.map((notice) => [notice.docName, notice.file]).sort()).toEqual(+ CONFIG_DOC_NAMES.map((configDoc) => [configDoc, files.get(configDoc)?.display]).sort(),+ );+ expect(notices.dismiss(CONFIG_DOC_NAMES[0], ids[0] as string)).toBe(true);+ expect((await notices.list('main')).map((notice) => notice.docName)).not.toContain(+ CONFIG_DOC_NAMES[0],+ );+ });++ test('a document whose file lives outside the content folder is checked at that file', async () => {+ const skillFile = join(projectDir, 'home', '.claude', 'skills', 'demo', 'SKILL.md');+ mkdirSync(dirname(skillFile), { recursive: true });+ writeFileSync(skillFile, '# Demo\n');+ const resolveFile = (docName: string): NoticeFile | null =>+ docName === '__skill__/global/demo'+ ? { abs: skillFile, display: '~/.claude/skills/demo/SKILL.md' }+ : null;+ const notices = ledger({ resolveFile });+ notices.record('__skill__/global/demo', 'main', { kind: 'both-kept', kept: KEPT_ONE });++ const listed = async () => (await notices.list('main')).map((notice) => notice.file);+ expect(await listed()).toEqual(['~/.claude/skills/demo/SKILL.md']);+ clock += NOTICE_WITHDRAW_AFTER_MS * 2;+ expect(await listed()).toEqual(['~/.claude/skills/demo/SKILL.md']);++ rmSync(skillFile);+ expect(await listed()).toEqual(['~/.claude/skills/demo/SKILL.md']);+ clock += NOTICE_WITHDRAW_AFTER_MS;+ expect(await listed()).toEqual([]);});test('a notice is withdrawn once its file has been missing on reads ten seconds apart', async () => {diff --git a/packages/server/src/doc-notices.ts b/packages/server/src/doc-notices.tsindex 8abe0ed67..0dc892a87 100644--- a/packages/server/src/doc-notices.ts+++ b/packages/server/src/doc-notices.ts@@ -3,7 +3,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';import { dirname, extname, join } from 'node:path';import { type DocNoticeWire, DocNoticeWireSchema } from '@inkeep/open-knowledge-core';import { z } from 'zod';-import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';+import { isSystemDoc } from './cc1-broadcast.ts';import { getLocalDir } from './config/paths.ts';import { docNameToRelativePath } from './doc-extensions.ts';import { tracedMkdirSync, tracedRenameSync, tracedWriteFileSync } from './fs-traced.ts';@@ -21,19 +21,35 @@ const MAX_ENTRIES_PER_NOTICE = 8;type BothKeptNotice = Extract<DocNoticeWire, { kind: 'both-kept' }>;type MovedNotice = Extract<DocNoticeWire, { kind: 'moved-to-history' }>;+type HeldNotice = Extract<DocNoticeWire, { kind: 'save-held' }>;++export type MoveReason = MovedNotice['reason'];export type DocNoticeEvent =| { kind: 'both-kept'; kept: BothKeptNotice['kept'] }| {kind: 'moved-to-history';side: MovedNotice['side'];- reason: MovedNotice['reason'];+ reason: MoveReason;entry: string;- };+ }+ | {+ kind: 'moved-to-backup';+ side: MovedNotice['side'];+ reason: MoveReason;+ backup: string;+ }+ | { kind: 'save-held'; cause: HeldNotice['cause'] };export interface DocNoticeSink {record(docName: string, branch: string, event: DocNoticeEvent): string | null;attachEntry(docName: string, id: string, entry: string): void;+ withdrawHeld(docName: string, branch: string): void;+}++export interface NoticeFile {+ readonly abs: string;+ readonly display: string;}export interface DocNoticeLedgerOptions {@@ -43,7 +59,9 @@ export interface DocNoticeLedgerOptions {isReady: () => boolean;signal: () => void;isHeld?: (docName: string) => boolean;+ isSaveHeld?: (docName: string) => boolean;now?: () => number;+ resolveFile?: (docName: string) => NoticeFile | null;}const StoredNoticeSchema = z.object({@@ -57,18 +75,56 @@ const StoredFileSchema = z.object({notices: z.array(z.unknown()),});-function keyOf(branch: string, docName: string): string {- return `${branch}\u0000${docName}`;+type NoticeSlot = 'kept' | 'held';++const NOTICE_SLOTS: readonly NoticeSlot[] = ['kept', 'held'];++function slotOf(kind: DocNoticeWire['kind']): NoticeSlot {+ return kind === 'save-held' ? 'held' : 'kept';+}++function keyOf(branch: string, docName: string, slot: NoticeSlot): string {+ return `${branch}\u0000${docName}\u0000${slot}`;}function isNoticeDoc(docName: string): boolean {- return !isSystemDoc(docName) && !isConfigDoc(docName);+ return !isSystemDoc(docName);}export function docNoticesPath(projectDir: string): string {return join(getLocalDir(projectDir), DOC_NOTICES_FILENAME);}+type NoticeCommon = Pick<+ DocNoticeWire,+ 'id' | 'docName' | 'file' | 'firstAt' | 'lastAt' | 'events' | 'entries'+>;++function noticeOf(common: NoticeCommon, event: DocNoticeEvent): DocNoticeWire {+ switch (event.kind) {+ case 'both-kept':+ return { ...common, kind: 'both-kept', kept: event.kept };+ case 'moved-to-history':+ return { ...common, kind: 'moved-to-history', side: event.side, reason: event.reason };+ case 'moved-to-backup':+ return {+ ...common,+ kind: 'moved-to-backup',+ side: event.side,+ reason: event.reason,+ backup: event.backup,+ };+ case 'save-held':+ return { ...common, kind: 'save-held', cause: event.cause };+ default:+ return assertNeverNoticeEvent(event);+ }+}++function assertNeverNoticeEvent(event: never): never {+ throw new Error(`unhandled notice event: ${JSON.stringify(event)}`);+}+export class DocNoticeLedger implements DocNoticeSink {private readonly options: DocNoticeLedgerOptions;private readonly storePath: string;@@ -83,14 +139,21 @@ export class DocNoticeLedger implements DocNoticeSink {record(docName: string, branch: string, event: DocNoticeEvent): string | null {if (!isNoticeDoc(docName)) return null;- const key = keyOf(branch, docName);+ const key = keyOf(branch, docName, slotOf(event.kind));const existing = this.byKey.get(key)?.notice;+ if (+ event.kind === 'save-held' &&+ existing?.kind === 'save-held' &&+ existing.cause === event.cause+ ) {+ return existing.id;+ }const at = new Date().toISOString();const entry = event.kind === 'moved-to-history' ? event.entry : undefined;const common = {id: existing?.id ?? randomUUID(),docName,- file: docNameToRelativePath(docName),+ file: this.options.resolveFile?.(docName)?.display ?? docNameToRelativePath(docName),firstAt: existing?.firstAt ?? at,lastAt: at,events: (existing?.events ?? 0) + 1,@@ -98,10 +161,7 @@ export class DocNoticeLedger implements DocNoticeSink {-MAX_ENTRIES_PER_NOTICE,),};- const notice: DocNoticeWire =- event.kind === 'both-kept'- ? { ...common, kind: 'both-kept', kept: event.kept }- : { ...common, kind: 'moved-to-history', side: event.side, reason: event.reason };+ const notice = noticeOf(common, event);this.byKey.delete(key);this.missingSince.delete(key);this.byKey.set(key, { branch, notice });@@ -117,6 +177,15 @@ export class DocNoticeLedger implements DocNoticeSink {return notice.id;}+ withdrawHeld(docName: string, branch: string): void {+ const key = keyOf(branch, docName, 'held');+ if (!this.byKey.has(key)) return;+ this.byKey.delete(key);+ this.missingSince.delete(key);+ log.info({ docName, branch }, `[doc-notices] held-save notice withdrawn: ${docName}`);+ this.commit();+ }+attachEntry(docName: string, id: string, entry: string): void {for (const [key, stored] of this.byKey) {if (stored.notice.docName !== docName || stored.notice.id !== id) continue;@@ -130,22 +199,27 @@ export class DocNoticeLedger implements DocNoticeSink {rename(oldDocName: string, newDocName: string, branch: string, newFile?: string): void {if (!isNoticeDoc(oldDocName) || !isNoticeDoc(newDocName)) return;- const oldKey = keyOf(branch, oldDocName);- const stored = this.byKey.get(oldKey);- if (!stored) return;- this.byKey.delete(oldKey);- this.missingSince.delete(oldKey);- const newKey = keyOf(branch, newDocName);- this.byKey.delete(newKey);- this.missingSince.delete(newKey);- this.byKey.set(newKey, {- branch,- notice: {- ...stored.notice,- docName: newDocName,- file: newFile ?? `${newDocName}${extname(stored.notice.file)}`,- },- });+ let moved = false;+ for (const slot of NOTICE_SLOTS) {+ const oldKey = keyOf(branch, oldDocName, slot);+ const stored = this.byKey.get(oldKey);+ if (!stored) continue;+ moved = true;+ this.byKey.delete(oldKey);+ this.missingSince.delete(oldKey);+ const newKey = keyOf(branch, newDocName, slot);+ this.byKey.delete(newKey);+ this.missingSince.delete(newKey);+ this.byKey.set(newKey, {+ branch,+ notice: {+ ...stored.notice,+ docName: newDocName,+ file: newFile ?? `${newDocName}${extname(stored.notice.file)}`,+ },+ });+ }+ if (!moved) return;log.info({ docName: newDocName, from: oldDocName, branch },`[doc-notices] notice followed a rename: ${oldDocName} -> ${newDocName}`,@@ -166,7 +240,14 @@ export class DocNoticeLedger implements DocNoticeSink {const gone: Array<[string, StoredNotice]> = [];const now = this.options.now?.() ?? Date.now();for (const [key, stored] of onBranch) {- const presence = this.filePresence(stored.notice.file);+ if (+ stored.notice.kind === 'save-held' &&+ this.options.isSaveHeld?.(stored.notice.docName) === false+ ) {+ gone.push([key, stored]);+ continue;+ }+ const presence = this.filePresence(stored.notice.docName, stored.notice.file);if (presence === 'present' || this.options.isHeld?.(stored.notice.docName) === true) {this.missingSince.delete(key);} else if (presence === 'missing') {@@ -204,9 +285,10 @@ export class DocNoticeLedger implements DocNoticeSink {return false;}- private filePresence(file: string): 'present' | 'missing' | 'unknown' {+ private filePresence(docName: string, file: string): 'present' | 'missing' | 'unknown' {+ const abs = this.options.resolveFile?.(docName)?.abs ?? join(this.options.contentDir, file);try {- statSync(join(this.options.contentDir, file));+ statSync(abs);return 'present';} catch (err) {const code = errnoCode(err);@@ -260,7 +342,10 @@ export class DocNoticeLedger implements DocNoticeSink {for (const row of file.notices) {const stored = StoredNoticeSchema.safeParse(row);if (!stored.success || !isNoticeDoc(stored.data.notice.docName)) continue;- this.byKey.set(keyOf(stored.data.branch, stored.data.notice.docName), stored.data);+ this.byKey.set(+ keyOf(stored.data.branch, stored.data.notice.docName, slotOf(stored.data.notice.kind)),+ stored.data,+ );}}diff --git a/packages/server/src/document-durability-state.test.ts b/packages/server/src/document-durability-state.test.tsindex 413fad837..42efc96e6 100644--- a/packages/server/src/document-durability-state.test.ts+++ b/packages/server/src/document-durability-state.test.ts@@ -48,6 +48,16 @@ describe('DocumentDurabilityState', () => {expect(state.takeStoreFailure('doc')).toBeNull();});+ test('records receipts for a document without giving it a reconciled base', () => {+ const state = new DocumentDurabilityState('main', { receipts: new DiskReceiptLog() });+ state.recordReceiptAgreed('flow.mmd', 'graph TD\n');+ expect(state.getReceipt('flow.mmd')).toMatchObject({ via: 'agreed' });+ state.recordReceiptOwnWrite('flow.mmd', 'graph LR\n');+ expect(state.getReceipt('flow.mmd')).toMatchObject({ via: 'own-write' });+ expect(state.isRecentOwnWrite('flow.mmd', contentHash('graph LR\n'))).toBe(true);+ expect(state.getReconciledBase('flow.mmd')).toBeUndefined();+ });+test('a batch held by two owners lasts until both release it, and only the last release ends it', () => {const state = new DocumentDurabilityState();state.holdBatch('head-watcher');diff --git a/packages/server/src/document-durability-state.ts b/packages/server/src/document-durability-state.tsindex f02381c51..b67bb8ecb 100644--- a/packages/server/src/document-durability-state.ts+++ b/packages/server/src/document-durability-state.ts@@ -425,6 +425,14 @@ export class DocumentDurabilityState {this.receipts.recordAgreed(docName, diskContent);}+ recordReceiptAgreed(docName: string, content: string, observation?: FileObservation): void {+ this.receipts.recordAgreed(docName, content, observation);+ }++ recordReceiptOwnWrite(docName: string, content: string, observation?: FileObservation): void {+ this.receipts.recordOwnWrite(docName, content, observation);+ }+setReconciledBase(docName: string, content: string, observation?: FileObservation): void {this.receipts.recordAgreed(docName, content, observation);let bases = this.reconciledBaseByBranch.get(this.activeBranch);diff --git a/packages/server/src/edit-backups.test.ts b/packages/server/src/edit-backups.test.tsnew file mode 100644index 000000000..4c23b6261--- /dev/null+++ b/packages/server/src/edit-backups.test.ts@@ -0,0 +1,59 @@+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { fnv1aDigest } from '@inkeep/open-knowledge-core';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import { backUpDisplacedVersion } from './edit-backups.ts';++let home: string;++beforeEach(() => {+ home = mkdtempSync(join(tmpdir(), 'ok-edit-backups-'));+});++afterEach(() => {+ vi.useRealTimers();+ rmSync(home, { recursive: true, force: true });+});++function discarded(...segments: string[]): string {+ return join(home, '.ok', 'edit-backups', 'discarded', ...segments);+}++function contentsOf(dir: string): string[] {+ return readdirSync(dir)+ .sort()+ .map((name) => readFileSync(join(dir, name), 'utf-8'));+}++describe('backUpDisplacedVersion', () => {+ test('a project document keeps its five newest copies in a folder of its own project, apart from another project with the same file', async () => {+ vi.useFakeTimers({ toFake: ['Date'] });+ for (let n = 1; n <= 6; n++) {+ vi.setSystemTime(Date.UTC(2026, 9, 21, 10, 0, n));+ await backUpDisplacedVersion(home, '/work/alpha', 'flow.mmd', `alpha ${n}\n`, 'flow.mmd');+ }+ const beta = await backUpDisplacedVersion(home, '/work/beta', 'flow.mmd', 'beta\n', 'flow.mmd');++ expect(contentsOf(discarded('projects', fnv1aDigest('/work/alpha'), 'flow.mmd'))).toEqual([+ 'alpha 2\n',+ 'alpha 3\n',+ 'alpha 4\n',+ 'alpha 5\n',+ 'alpha 6\n',+ ]);+ expect(contentsOf(discarded('projects', fnv1aDigest('/work/beta'), 'flow.mmd'))).toEqual([+ 'beta\n',+ ]);+ expect(beta?.display).toBe(+ `~/.ok/edit-backups/discarded/projects/${fnv1aDigest('/work/beta')}/flow.mmd/2026-10-21T10-00-06-000Z.mmd`,+ );+ });++ test('a document with no project keeps the folder it had before', async () => {+ await backUpDisplacedVersion(home, null, '__skill__/global/demo', 'outside\n', 'SKILL.md');++ expect(readdirSync(discarded())).toEqual(['__skill____global__demo']);+ expect(contentsOf(discarded('__skill____global__demo'))).toEqual(['outside\n']);+ });+});diff --git a/packages/server/src/edit-backups.ts b/packages/server/src/edit-backups.tsnew file mode 100644index 000000000..176c3f453--- /dev/null+++ b/packages/server/src/edit-backups.ts@@ -0,0 +1,93 @@+import { createHash } from 'node:crypto';+import { readdirSync } from 'node:fs';+import { extname, resolve } from 'node:path';+import {+ fnv1aDigest,+ MANAGED_ARTIFACT_PREFIX_EXTSKILL,+ MANAGED_ARTIFACT_PREFIX_SKILL,+ MANAGED_ARTIFACT_PREFIX_TEMPLATE,+} from '@inkeep/open-knowledge-core';+import { atomicWriteFile, okUserHomeDir } from '@inkeep/open-knowledge-core/server';+import { displayPathFor } from './display-path.ts';+import { tracedAtomicFs, tracedMkdir, tracedUnlinkSync } from './fs-traced.ts';+import { getLogger } from './logger.ts';+import {+ incrementDisplacedVersionBackupFailures,+ incrementDisplacedVersionBackups,+} from './metrics.ts';++const log = getLogger('edit-backups');++const DISCARDED_EDIT_STASH_MAX = 5;+const DISCARDED_EDIT_READABLE_MAX = 100;+const DISCARDED_EDIT_DIGEST_LEN = 12;+const UNAMBIGUOUS_STASH_SEGMENT_RE = /^(?!.*__)[A-Za-z0-9.-](?:[A-Za-z0-9._-]*[A-Za-z0-9.-])?$/;++export interface BackupCopy {+ readonly abs: string;+ readonly display: string;+}++function discardedEditStashKey(documentName: string): string {+ const legacy = documentName.replace(/[^A-Za-z0-9._-]+/g, '__');+ const prefix = [+ MANAGED_ARTIFACT_PREFIX_SKILL,+ MANAGED_ARTIFACT_PREFIX_TEMPLATE,+ MANAGED_ARTIFACT_PREFIX_EXTSKILL,+ ].find((p) => documentName.startsWith(p));+ const rest = prefix === undefined ? documentName : documentName.slice(prefix.length);+ if (rest.split('/').every((segment) => UNAMBIGUOUS_STASH_SEGMENT_RE.test(segment))) {+ return legacy;+ }+ const canonical = documentName.normalize('NFC');+ const digest = createHash('sha256')+ .update(canonical)+ .digest('hex')+ .slice(0, DISCARDED_EDIT_DIGEST_LEN);+ const readable = canonical+ .replace(/[^A-Za-z0-9._-]+/g, '__')+ .replace(/^\.+/, '_')+ .slice(0, DISCARDED_EDIT_READABLE_MAX);+ return `${readable}-${digest}`;+}++function backupFolder(home: string, project: string | null, documentName: string): string {+ const discarded = resolve(okUserHomeDir(home), 'edit-backups', 'discarded');+ const key = discardedEditStashKey(documentName);+ return project === null+ ? resolve(discarded, key)+ : resolve(discarded, 'projects', fnv1aDigest(project), key);+}++export async function backUpDisplacedVersion(+ home: string,+ project: string | null,+ documentName: string,+ content: string,+ fileName: string,+): Promise<BackupCopy | null> {+ try {+ const dir = backupFolder(home, project, documentName);+ await tracedMkdir(dir, { recursive: true });+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');+ const abs = resolve(dir, `${stamp}${extname(fileName)}`);+ await atomicWriteFile(abs, content, { fs: tracedAtomicFs });+ const entries = readdirSync(dir).sort();+ for (const old of entries.slice(0, Math.max(0, entries.length - DISCARDED_EDIT_STASH_MAX))) {+ try {+ tracedUnlinkSync(resolve(dir, old));+ } catch {}+ }+ incrementDisplacedVersionBackups();+ const copy = { abs, display: displayPathFor(abs, null, home) };+ log.info(+ { documentName, backup: copy.display },+ 'a displaced version was kept in the backup folder',+ );+ return copy;+ } catch (err) {+ incrementDisplacedVersionBackupFailures();+ log.warn({ documentName, err }, 'a displaced version could not be kept in the backup folder');+ return null;+ }+}diff --git a/packages/server/src/external-change.ts b/packages/server/src/external-change.tsindex 139cd780a..06cb4dbef 100644--- a/packages/server/src/external-change.ts+++ b/packages/server/src/external-change.ts@@ -5,6 +5,7 @@ import {BridgeMergeContentLossError,type DiskEditReconciledWarning,normalizeBridge,+ type ParsedCheckpoint,prependFrontmatter,type ReconcileMergeOutcome,stripFrontmatter,@@ -255,7 +256,12 @@ function clearStaleExternalWriteConflict(lifecycleMap.delete('detectedAt');}-type ReconcileCheckSite = 'watcher' | 'agent-write' | 'branch-switch';+type ReconcileCheckSite =+ | 'watcher'+ | 'agent-write'+ | 'branch-switch'+ | 'skill-store'+ | 'skill-intake';export function reportReconcileCheckFailed(docName: string,@@ -285,7 +291,7 @@ export function reportReconcileBothKept(export function reportReconcileKeptLive(docName: string,- reason: 'check-failed' | 'too-large',+ reason: Extract<ParsedCheckpoint, { kind: 'external-change-kept-live' }>['metadata']['reason'],site: ReconcileCheckSite,): void {incrementReconcileKeptLive();diff --git a/packages/server/src/managed-artifact-persistence.test.ts b/packages/server/src/managed-artifact-persistence.test.tsindex 01bf6e178..8f583bc96 100644--- a/packages/server/src/managed-artifact-persistence.test.ts+++ b/packages/server/src/managed-artifact-persistence.test.ts@@ -1,4 +1,5 @@import {+ chmodSync,existsSync,mkdirSync,mkdtempSync,@@ -10,10 +11,11 @@ import {import { tmpdir } from 'node:os';import { dirname, join, resolve, sep } from 'node:path';import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';-import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import * as Y from 'yjs';import { FILE_WATCHER_ORIGIN } from './external-change.ts';import { registerExternalSkill, unregisterExternalSkill } from './external-skill-registry.ts';+import * as fsTraced from './fs-traced.ts';import {applyExternalManagedArtifactChange,loadManagedArtifactDoc,@@ -25,18 +27,55 @@ import {managedArtifactTimelinePaths,storeManagedArtifactDoc,} from './managed-artifact-persistence.ts';+import type { MergeHistoryRecorder } from './merge-history.ts';+import { getMetrics, resetMetrics } from './metrics.ts';+import type { KeptBlockPair } from './reconciliation.ts';let projectDir: string;let home: string;let reconciled: Map<string, string>;-function makeCtx(): ManagedArtifactCtx {+function makeCtx(history: ManagedArtifactCtx['history'] = null): ManagedArtifactCtx {return {projectDir,homedirOverride: home,lkgCache: new Map<string, string>(),setReconciledBase: (n, c) => reconciled.set(n, c),getReconciledBase: (n) => reconciled.get(n),+ history,+ };+}++interface RecordedHistory {+ bothKept: Array<{ docName: string; ours: string; theirs: string; kept: KeptBlockPair[] }>;+ keptLive: Array<{ docName: string; side: string; bytes: string; reason: string }>;+ backups: Array<{ docName: string; side: string; reason: string; display: string }>;+}++function recordingHistory(+ keptLiveSaves = true,+ duringKeptLive?: () => void,+): {+ history: Pick<MergeHistoryRecorder, 'bothKept' | 'keptLive' | 'noticeBackup'>;+ recorded: RecordedHistory;+} {+ const recorded: RecordedHistory = { bothKept: [], keptLive: [], backups: [] };+ return {+ recorded,+ history: {+ bothKept: (docName, versions, kept) => {+ recorded.bothKept.push({ docName, ...versions, kept: [...kept] });+ },+ keptLive: async (docName, displaced, reason) => {+ duringKeptLive?.();+ if (!keptLiveSaves) return false;+ recorded.keptLive.push({ docName, ...displaced, reason });+ return true;+ },+ noticeBackup: (docName, side, reason, backup) => {+ recorded.backups.push({ docName, side, reason, display: backup.display });+ },+ },};}@@ -48,8 +87,10 @@ beforeEach(() => {projectDir = mkdtempSync(join(tmpdir(), 'ok-ma-proj-'));home = mkdtempSync(join(tmpdir(), 'ok-ma-home-'));reconciled = new Map();+ resetMetrics();});afterEach(() => {+ vi.restoreAllMocks();rmSync(projectDir, { recursive: true, force: true });rmSync(home, { recursive: true, force: true });});@@ -331,19 +372,19 @@ describe('store/load round-trip', () => {describe('discarded-edit backups', () => {beforeEach(adoptClaudeHost);- async function reconcileLocalEdit(docName: string, localEdit: string): Promise<void> {+ async function reconcileLocalEdit(docName: string, outsideText: string): Promise<void> {const ctx = makeCtx();const path = managedArtifactAbsPath(docName, ctx);mkdirSync(dirname(path), { recursive: true });const doc = new Y.Doc();doc.transact(() => doc.getText('source').insert(0, 'base\n'), 'agent');await storeManagedArtifactDoc(doc, docName, 'agent', ctx);- writeFileSync(path, 'other writer\n', 'utf-8');+ writeFileSync(path, `<<<<<<< here\n${outsideText}\n=======\nbase\n>>>>>>> there\n`, 'utf-8');doc.transact(- () => doc.getText('source').insert(doc.getText('source').length, localEdit),+ () => doc.getText('source').insert(doc.getText('source').length, 'local'),'agent',);- expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('reconciled');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('stash-fallback');}function backupDirs(): string[] {@@ -391,117 +432,456 @@ describe('discarded-edit backups', () => {});});-describe('concurrent-writer reconcile', () => {+describe('an outside change to a global skill', () => {const docName = '__skill__/global/demo';+ const SAVED = '---\nname: demo\ndescription: a\n---\n\nFirst.\n\nSecond.\n';+ const HERE = '---\nname: demo\ndescription: a\n---\n\nFirst, here.\n\nSecond.\n';+ const OUTSIDE_SAME_BLOCK = '---\nname: demo\ndescription: a\n---\n\nFirst, outside.\n\nSecond.\n';+ const BOTH_KEPT =+ '---\nname: demo\ndescription: a\n---\n\nFirst, here.\n\nFirst, outside.\n\nSecond.\n';+ const OUTSIDE_OTHER_BLOCK =+ '---\nname: demo\ndescription: a\n---\n\nFirst.\n\nSecond, outside.\n';+ const MERGED = '---\nname: demo\ndescription: a\n---\n\nFirst, here.\n\nSecond, outside.\n';+ const OUTSIDE_WITH_MARKERS =+ '---\nname: demo\ndescription: a\n---\n\n<<<<<<< ours\nFirst, ours.\n=======\nFirst, theirs.\n>>>>>>> theirs\n\nSecond.\n';++ let path: string;beforeEach(() => {adoptClaudeHost();- mkdirSync(dirname(managedArtifactAbsPath(docName, makeCtx())), { recursive: true });+ path = managedArtifactAbsPath(docName, makeCtx());+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, SAVED, 'utf-8');});- test('store reconciles instead of clobbering when disk diverged from LKG', async () => {- const ctx = makeCtx();+ function openSaved(ctx: ManagedArtifactCtx): Y.Doc {const doc = new Y.Doc();- doc.transact(- () => doc.getText('source').insert(0, '---\nname: demo\ndescription: a\n---\nA\n'),- 'agent',- );- await storeManagedArtifactDoc(doc, docName, 'agent', ctx);+ loadManagedArtifactDoc(doc, docName, ctx);+ return doc;+ }- const path = managedArtifactAbsPath(docName, ctx);- const otherWriter = '---\nname: demo\ndescription: a\n---\nOTHER WRITER\n';- writeFileSync(path, otherWriter, 'utf-8');+ function editTo(doc: Y.Doc, text: string): void {+ doc.transact(() => {+ const src = doc.getText('source');+ src.delete(0, src.length);+ src.insert(0, text);+ }, 'agent');+ }- doc.transact(- () => doc.getText('source').insert(doc.getText('source').length, 'local edit'),- 'agent',+ function stashedFiles(): string[] {+ const root = resolve(home, '.ok', 'edit-backups', 'discarded');+ if (!existsSync(root)) return [];+ return readdirSync(root).flatMap((dir) =>+ readdirSync(resolve(root, dir)).map((f) => readFileSync(resolve(root, dir, f), 'utf-8')),);- const outcome = await storeManagedArtifactDoc(doc, docName, 'agent', ctx);- expect(outcome).toBe('reconciled');- expect(readFileSync(path, 'utf-8')).toBe(otherWriter);- expect(reconciled.get(docName)).toBe(otherWriter);+ }++ test('a same-block collision at the store keeps both versions live and on disk, with both pre-merge versions recorded', async () => {+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('both-kept');++ expect(doc.getText('source').toString()).toBe(BOTH_KEPT);+ expect(readFileSync(path, 'utf-8')).toBe(BOTH_KEPT);+ expect(reconciled.get(docName)).toBe(BOTH_KEPT);+ expect(recorded.bothKept).toHaveLength(1);+ expect(recorded.bothKept[0]).toMatchObject({ docName, ours: HERE, theirs: OUTSIDE_SAME_BLOCK });+ expect(stashedFiles()).toEqual([]);+ expect(getMetrics().managedArtifactMerge).toEqual({ 'store:both-kept': 1 });+ });- const safe = docName.replace(/[^A-Za-z0-9._-]+/g, '__');- const stashDir = resolve(home, '.ok', 'edit-backups', 'discarded', safe);- const stashed = readdirSync(stashDir);- expect(stashed).toHaveLength(1);- expect(readFileSync(resolve(stashDir, stashed[0] as string), 'utf-8')).toContain('local edit');+ test('edits to different blocks merge at the store with no history entry', async () => {+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_OTHER_BLOCK, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('merged');++ expect(doc.getText('source').toString()).toBe(MERGED);+ expect(readFileSync(path, 'utf-8')).toBe(MERGED);+ expect(recorded).toEqual({ bothKept: [], keptLive: [], backups: [] });+ });++ test('an outside version that cannot be merged leaves the version here live and on disk and goes to history', async () => {+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_WITH_MARKERS, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('kept-live');++ expect(doc.getText('source').toString()).toBe(HERE);+ expect(readFileSync(path, 'utf-8')).toBe(HERE);+ expect(recorded.keptLive).toEqual([+ { docName, side: 'theirs', bytes: OUTSIDE_WITH_MARKERS, reason: 'conflict-markers' },+ ]);+ expect(stashedFiles()).toEqual([]);+ });++ test('a file that appears under a skill typed into before it existed keeps the version here', async () => {+ rmSync(path);+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('kept-live');++ expect(doc.getText('source').toString()).toBe(HERE);+ expect(readFileSync(path, 'utf-8')).toBe(HERE);+ expect(recorded.keptLive).toEqual([+ { docName, side: 'theirs', bytes: OUTSIDE_SAME_BLOCK, reason: 'no-base' },+ ]);+ });++ test('when history cannot hold the outside version it goes to the discarded-edit backups, with a notice naming the file', async () => {+ const { history, recorded } = recordingHistory(false);+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_WITH_MARKERS, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('stash-fallback');++ expect(readFileSync(path, 'utf-8')).toBe(HERE);+ expect(stashedFiles()).toEqual([OUTSIDE_WITH_MARKERS]);+ expect(recorded.backups).toEqual([+ {+ docName,+ side: 'theirs',+ reason: 'conflict-markers',+ display: expect.stringMatching(+ /^~\/\.ok\/edit-backups\/discarded\/__skill____global__demo\/.+\.md$/,+ ),+ },+ ]);+ });++ test('when neither history nor the stash can take the outside version, nothing is written', async () => {+ mkdirSync(join(home, '.ok'), { recursive: true });+ writeFileSync(join(home, '.ok', 'edit-backups'), 'not a folder');+ const { history } = recordingHistory(false);+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_WITH_MARKERS, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toEqual({+ kind: 'held',+ cause: 'no-history-or-backup',+ });++ expect(readFileSync(path, 'utf-8')).toBe(OUTSIDE_WITH_MARKERS);+ expect(doc.getText('source').toString()).toBe(HERE);+ expect(getMetrics().managedArtifactMerge).toEqual({ 'store:held': 1 });});- test('reconcile invokes beforeReconcileDivergence with the live and disk content', async () => {- const calls: Array<{ docName: string; live: string; disk: string }> = [];+ test('an outside write during the history save of a refused merge is taken in before anything is written', async () => {+ const later = OUTSIDE_OTHER_BLOCK;+ let planted = false;+ const { history, recorded } = recordingHistory(true, () => {+ if (planted) return;+ planted = true;+ writeFileSync(path, later, 'utf-8');+ });+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_WITH_MARKERS, 'utf-8');++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('merged');++ expect(readFileSync(path, 'utf-8')).toBe(MERGED);+ expect(doc.getText('source').toString()).toBe(MERGED);+ expect(recorded.keptLive.map((entry) => entry.bytes)).toEqual([OUTSIDE_WITH_MARKERS]);+ });++ test('an outside write between the compare and the rename is refused and merged on the next round', async () => {+ const { history } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ const write = fsTraced.tracedAtomicFs.writeFile;+ let planted = false;+ vi.spyOn(fsTraced.tracedAtomicFs, 'writeFile').mockImplementation(async (...args) => {+ await write(...args);+ if (planted) return;+ planted = true;+ writeFileSync(path, OUTSIDE_OTHER_BLOCK, 'utf-8');+ });++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('merged');++ expect(readFileSync(path, 'utf-8')).toBe(MERGED);+ expect(getMetrics().storeRestatRefused).toBe(1);+ });++ test('an outside write between the compare and the rename of a both-kept merge leaves the live doc alone, and the retry records both pre-merge versions', async () => {+ const OUTSIDE_AGAIN =+ '---\nname: demo\ndescription: a\n---\n\nFirst, outside again.\n\nSecond.\n';+ const BOTH_KEPT_AGAIN =+ '---\nname: demo\ndescription: a\n---\n\nFirst, here.\n\nFirst, outside again.\n\nSecond.\n';+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');+ const write = fsTraced.tracedAtomicFs.writeFile;+ let liveAtPlant: string | undefined;+ vi.spyOn(fsTraced.tracedAtomicFs, 'writeFile').mockImplementation(async (...args) => {+ await write(...args);+ if (liveAtPlant !== undefined) return;+ liveAtPlant = doc.getText('source').toString();+ writeFileSync(path, OUTSIDE_AGAIN, 'utf-8');+ });++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('both-kept');++ expect(liveAtPlant).toBe(HERE);+ expect(doc.getText('source').toString()).toBe(BOTH_KEPT_AGAIN);+ expect(readFileSync(path, 'utf-8')).toBe(BOTH_KEPT_AGAIN);+ expect(doc.getText('source').toString().split('First, here.')).toHaveLength(2);+ expect(recorded.bothKept).toHaveLength(1);+ expect(recorded.bothKept[0]).toMatchObject({ docName, ours: HERE, theirs: OUTSIDE_AGAIN });+ expect(getMetrics().storeRestatRefused).toBe(1);+ });++ test('an outside version that is not valid UTF-8 is neither merged nor written over, at the save or the intake', async () => {+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ const latin1 = Buffer.from(OUTSIDE_SAME_BLOCK.replace('outside', 'caf\u00e9'), 'latin1');+ writeFileSync(path, latin1);++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toMatchObject({+ kind: 'held',+ cause: 'not-utf8',+ path,+ });+ expect(+ await applyExternalManagedArtifactChange(doc, docName, latin1.toString('utf8'), ctx),+ ).toBe('held');++ expect(readFileSync(path).equals(latin1)).toBe(true);+ expect(doc.getText('source').toString()).toBe(HERE);+ expect(recorded).toEqual({ bothKept: [], keptLive: [], backups: [] });+ expect(stashedFiles()).toEqual([]);+ expect(getMetrics().managedArtifactMerge).toEqual({ 'store:held': 1, 'intake:held': 1 });+ });++ test('the polled intake reports a lock timeout as held, and lets any other failure reach the watcher', async () => {+ const ctx = makeCtx(recordingHistory().history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');+ const lock = `${path}.lock`;+ writeFileSync(lock, '');+ vi.useFakeTimers({ toFake: ['Date', 'setTimeout'] });+ try {+ const intake = applyExternalManagedArtifactChange(doc, docName, OUTSIDE_SAME_BLOCK, ctx);+ await vi.advanceTimersByTimeAsync(6_000);+ expect(await intake).toBe('held');+ } finally {+ vi.useRealTimers();+ rmSync(lock, { force: true });+ }+ expect(doc.getText('source').toString()).toBe(HERE);+ expect(getMetrics().managedArtifactMerge).toEqual({ 'intake:held': 1 });++ const failure = new Error('merge defect');+ const failing: ManagedArtifactCtx = {+ ...ctx,+ beforeReconcileDivergence: () => {+ throw failure;+ },+ };+ await expect(+ applyExternalManagedArtifactChange(doc, docName, OUTSIDE_SAME_BLOCK, failing),+ ).rejects.toBe(failure);+ expect(readFileSync(path, 'utf-8')).toBe(OUTSIDE_SAME_BLOCK);+ });++ test('a merge the polled intake writes while a save waits for the lock is not written over', async () => {+ const { history } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');+ const mkdir = fsTraced.tracedMkdir;+ let intake: Promise<unknown> | undefined;+ vi.spyOn(fsTraced, 'tracedMkdir').mockImplementation(async (...args) => {+ if (intake === undefined) {+ intake = applyExternalManagedArtifactChange(doc, docName, OUTSIDE_SAME_BLOCK, ctx);+ await intake;+ }+ return mkdir(...args);+ });++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('no-op');++ expect(await intake).toBe('both-kept');+ expect(readFileSync(path, 'utf-8')).toBe(BOTH_KEPT);+ expect(doc.getText('source').toString()).toBe(BOTH_KEPT);+ });++ test.skipIf(process.getuid?.() === 0)(+ 'writes nothing when the file cannot be read for the compare',+ async () => {+ const ctx = makeCtx(recordingHistory().history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ chmodSync(path, 0o000);+ try {+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toEqual({+ kind: 'held',+ cause: 'unreadable',+ });+ } finally {+ chmodSync(path, 0o644);+ }+ expect(readFileSync(path, 'utf-8')).toBe(SAVED);+ },+ );++ test('the paired apply hands the loss detector the version here and the text it applies', async () => {+ const calls: Array<{ docName: string; live: string; applied: string }> = [];const ctx: ManagedArtifactCtx = {- ...makeCtx(),- beforeReconcileDivergence: (_doc, name, live, disk) => {- calls.push({ docName: name, live, disk });+ ...makeCtx(recordingHistory().history),+ beforeReconcileDivergence: (_doc, name, live, applied) => {+ calls.push({ docName: name, live, applied });return undefined;},};- const doc = new Y.Doc();- const v1 = '---\nname: demo\ndescription: a\n---\nA\n';- doc.transact(() => doc.getText('source').insert(0, v1), 'agent');- await storeManagedArtifactDoc(doc, docName, 'agent', ctx);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('persisted');expect(calls).toHaveLength(0);- const path = managedArtifactAbsPath(docName, ctx);- const otherWriter = '---\nname: demo\ndescription: a\n---\nOTHER WRITER\n';- writeFileSync(path, otherWriter, 'utf-8');-- doc.transact(- () => doc.getText('source').insert(doc.getText('source').length, 'local edit'),- 'agent',- );+ editTo(doc, `${HERE}\nThird, here.\n`);+ writeFileSync(path, OUTSIDE_OTHER_BLOCK.replace('First.', 'First, here.'), 'utf-8');const live = doc.getText('source').toString();- expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('reconciled');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('merged');- expect(calls).toHaveLength(1);- expect(calls[0]?.docName).toBe(docName);- expect(calls[0]?.live).toBe(live);- expect(calls[0]?.live).toContain('local edit');- expect(calls[0]?.disk).toBe(otherWriter);+ expect(calls).toEqual([{ docName, live, applied: doc.getText('source').toString() }]);});- test('reconcile still returns reconciled when no checkpoint hook is wired', async () => {- const ctx = makeCtx();+ test('the store still merges when no checkpoint hook is wired', async () => {+ const ctx = makeCtx(recordingHistory().history);expect(ctx.beforeReconcileDivergence).toBeUndefined();- const doc = new Y.Doc();- doc.transact(- () => doc.getText('source').insert(0, '---\nname: demo\ndescription: a\n---\nA\n'),- 'agent',+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('both-kept');+ });++ test('the polled intake applies a refresh of a skill nobody edited, with no history', async () => {+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ writeFileSync(path, OUTSIDE_OTHER_BLOCK, 'utf-8');++ expect(await applyExternalManagedArtifactChange(doc, docName, OUTSIDE_OTHER_BLOCK, ctx)).toBe(+ 'applied',);- await storeManagedArtifactDoc(doc, docName, 'agent', ctx);- const path = managedArtifactAbsPath(docName, ctx);- writeFileSync(path, '---\nname: demo\ndescription: a\n---\nOTHER\n', 'utf-8');- doc.transact(() => doc.getText('source').insert(doc.getText('source').length, 'x'), 'agent');- expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('reconciled');++ expect(doc.getText('source').toString()).toBe(OUTSIDE_OTHER_BLOCK);+ expect(reconciled.get(docName)).toBe(OUTSIDE_OTHER_BLOCK);+ expect(recorded).toEqual({ bothKept: [], keptLive: [], backups: [] });});- test('applyExternalManagedArtifactChange imports disk bytes into the live doc', () => {- const ctx = makeCtx();- const doc = new Y.Doc();- const raw = '---\nname: demo\ndescription: a\n---\nEXTERNAL\n';- expect(applyExternalManagedArtifactChange(doc, docName, raw, ctx)).toBe('applied');- expect(doc.getText('source').toString()).toBe(raw);- expect(reconciled.get(docName)).toBe(raw);+ test('the polled intake keeps both versions of a block edited on both sides and writes the result', async () => {+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_SAME_BLOCK, 'utf-8');++ expect(await applyExternalManagedArtifactChange(doc, docName, OUTSIDE_SAME_BLOCK, ctx)).toBe(+ 'both-kept',+ );++ expect(doc.getText('source').toString()).toBe(BOTH_KEPT);+ expect(readFileSync(path, 'utf-8')).toBe(BOTH_KEPT);+ expect(recorded.bothKept).toHaveLength(1);+ expect(getMetrics().managedArtifactMerge).toEqual({ 'intake:both-kept': 1 });});- test('applyExternalManagedArtifactChange is a no-op for a null doc', () => {+ test('the polled intake takes nothing in when the file moved on since the poll', async () => {+ const ctx = makeCtx(recordingHistory().history);+ const doc = openSaved(ctx);+ editTo(doc, HERE);+ writeFileSync(path, OUTSIDE_OTHER_BLOCK, 'utf-8');++ expect(await applyExternalManagedArtifactChange(doc, docName, OUTSIDE_SAME_BLOCK, ctx)).toBe(+ 'no-op',+ );+ expect(doc.getText('source').toString()).toBe(HERE);+ });++ test('applyExternalManagedArtifactChange is a no-op for a null doc', async () => {const ctx = makeCtx();- expect(applyExternalManagedArtifactChange(null, docName, 'whatever', ctx)).toBe('no-op');+ expect(await applyExternalManagedArtifactChange(null, docName, 'whatever', ctx)).toBe('no-op');expect(reconciled.has(docName)).toBe(false);});- test('applyExternalManagedArtifactChange short-circuits a self-write (content === LKG)', () => {+ test('applyExternalManagedArtifactChange short-circuits a self-write (content === LKG)', async () => {const ctx = makeCtx();const doc = new Y.Doc();const raw = '---\nname: demo\ndescription: a\n---\nBODY\n';ctx.lkgCache.set(docName, raw);- expect(applyExternalManagedArtifactChange(doc, docName, raw, ctx)).toBe('no-op');+ expect(await applyExternalManagedArtifactChange(doc, docName, raw, ctx)).toBe('no-op');expect(doc.getText('source').toString()).toBe('');expect(reconciled.has(docName)).toBe(false);});});+describe('an outside change to an external skill', () => {+ let skillDir: string;++ beforeEach(() => {+ skillDir = mkdtempSync(join(tmpdir(), 'ok-ma-ext-'));+ writeFileSync(join(skillDir, 'SKILL.md'), '# External\n\nFirst.\n\nSecond.\n', 'utf-8');+ registerExternalSkill('ext-merge', skillDir);+ });+ afterEach(() => {+ unregisterExternalSkill('ext-merge');+ rmSync(skillDir, { recursive: true, force: true });+ });++ test('a same-block collision at the store keeps both versions', async () => {+ const docName = '__extskill__/ext-merge';+ const { history, recorded } = recordingHistory();+ const ctx = makeCtx(history);+ const doc = new Y.Doc();+ loadManagedArtifactDoc(doc, docName, ctx);+ doc.transact(() => {+ const src = doc.getText('source');+ src.delete(0, src.length);+ src.insert(0, '# External\n\nFirst, here.\n\nSecond.\n');+ }, 'agent');+ writeFileSync(+ join(skillDir, 'SKILL.md'),+ '# External\n\nFirst, outside.\n\nSecond.\n',+ 'utf-8',+ );++ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('both-kept');+ expect(readFileSync(join(skillDir, 'SKILL.md'), 'utf-8')).toBe(+ '# External\n\nFirst, here.\n\nFirst, outside.\n\nSecond.\n',+ );+ expect(recorded.bothKept).toHaveLength(1);+ });+});+describe('managedArtifactDocNameForPath (reverse resolver)', () => {beforeEach(adoptClaudeHost);diff --git a/packages/server/src/managed-artifact-persistence.ts b/packages/server/src/managed-artifact-persistence.tsindex 8d0a1db43..cd567632b 100644--- a/packages/server/src/managed-artifact-persistence.ts+++ b/packages/server/src/managed-artifact-persistence.ts@@ -4,14 +4,12 @@* re-canonicalize the markdown that gets projected verbatim into an agent's context).*/-import { createHash } from 'node:crypto';-import { existsSync, readdirSync, readFileSync } from 'node:fs';+import { existsSync, readFileSync } from 'node:fs';import { homedir } from 'node:os';import { dirname, relative, resolve, sep } from 'node:path';import {LEGACY_SKILL_STORE_ROOT,LINEAGE_EPOCH_KEY,- MANAGED_ARTIFACT_PREFIX_EXTSKILL,MANAGED_ARTIFACT_PREFIX_SKILL,MANAGED_ARTIFACT_PREFIX_TEMPLATE,type ManagedArtifactScope,@@ -29,8 +27,15 @@ import {import type * as Y from 'yjs';import type { DeriveLossDetectOptions } from './bridge-loss-detector.ts';import { applyDiskContentToDoc, FILE_WATCHER_ORIGIN } from './disk-content-intake.ts';+import type { FileObservation } from './disk-receipts.ts';+import { backUpDisplacedVersion } from './edit-backups.ts';+import {+ reportReconcileBothKept,+ reportReconcileCheckFailed,+ reportReconcileKeptLive,+} from './external-change.ts';import { externalSkillAbsPath } from './external-skill-registry.ts';-import { tracedAtomicFs, tracedMkdir, tracedUnlinkSync } from './fs-traced.ts';+import { tracedAtomicFs, tracedMkdir } from './fs-traced.ts';import {globalSkillGraphRoots,knownSkillRootsFor,@@ -38,7 +43,22 @@ import {resolveGlobalNativeSkillDir,} from './in-place-skills.ts';import { getLogger } from './logger.ts';-import { incrementManagedArtifactReconcile } from './metrics.ts';+import type { MergeHistoryRecorder } from './merge-history.ts';+import {+ incrementManagedArtifactMerge,+ incrementManagedArtifactReconcile,+ incrementStoreRestatRefused,+ type ManagedArtifactMergeOutcome,+} from './metrics.ts';+import { reconcile } from './reconciliation.ts';+import { heldFor, heldNotUtf8, type SaveHold } from './save-hold.ts';+import {+ type ObservedTextRead,+ readObservedText,+ restatFile,+ StoreRestatFailedError,+ StoreRestatRefusedError,+} from './store-compare.ts';const log = getLogger('managed-artifact-persistence');@@ -54,9 +74,40 @@ export interface ManagedArtifactCtx {liveContent: string,diskContent: string,) => DeriveLossDetectOptions | undefined;+ history: Pick<MergeHistoryRecorder, 'bothKept' | 'keptLive' | 'noticeBackup'> | null;+}++type SettledMergeOutcome = Exclude<ManagedArtifactMergeOutcome, 'held'>;++export type StoreManagedArtifactOutcome =+ | 'persisted'+ | 'no-op'+ | 'write-failed'+ | SettledMergeOutcome+ | SaveHold;++export function storeManagedArtifactWroteFile(outcome: StoreManagedArtifactOutcome): boolean {+ if (typeof outcome === 'object') return false;+ switch (outcome) {+ case 'persisted':+ case 'merged':+ case 'both-kept':+ case 'kept-live':+ case 'stash-fallback':+ return true;+ case 'no-op':+ case 'write-failed':+ case 'applied':+ case 'unchanged':+ return false;+ default:+ return assertNeverStoreOutcome(outcome);+ }}-export type StoreManagedArtifactOutcome = 'persisted' | 'no-op' | 'reconciled' | 'write-failed';+function assertNeverStoreOutcome(outcome: never): never {+ throw new Error(`unhandled skill store outcome: ${String(outcome)}`);+}type ManagedArtifactLocation = Pick<ManagedArtifactCtx, 'projectDir' | 'homedirOverride'>;@@ -254,60 +305,6 @@ export function loadManagedArtifactDoc(ctx.lkgCache.set(documentName, raw);}-const DISCARDED_EDIT_STASH_MAX = 5;-const DISCARDED_EDIT_READABLE_MAX = 100;-const DISCARDED_EDIT_DIGEST_LEN = 12;-const UNAMBIGUOUS_STASH_SEGMENT_RE = /^(?!.*__)[A-Za-z0-9.-](?:[A-Za-z0-9._-]*[A-Za-z0-9.-])?$/;--function discardedEditStashKey(documentName: string): string {- const legacy = documentName.replace(/[^A-Za-z0-9._-]+/g, '__');- const prefix = [- MANAGED_ARTIFACT_PREFIX_SKILL,- MANAGED_ARTIFACT_PREFIX_TEMPLATE,- MANAGED_ARTIFACT_PREFIX_EXTSKILL,- ].find((p) => documentName.startsWith(p));- const rest = prefix === undefined ? documentName : documentName.slice(prefix.length);- if (rest.split('/').every((segment) => UNAMBIGUOUS_STASH_SEGMENT_RE.test(segment))) {- return legacy;- }- const canonical = documentName.normalize('NFC');- const digest = createHash('sha256')- .update(canonical)- .digest('hex')- .slice(0, DISCARDED_EDIT_DIGEST_LEN);- const readable = canonical- .replace(/[^A-Za-z0-9._-]+/g, '__')- .replace(/^\.+/, '_')- .slice(0, DISCARDED_EDIT_READABLE_MAX);- return `${readable}-${digest}`;-}--async function stashDiscardedEdit(- documentName: string,- content: string,- ctx: Pick<ManagedArtifactCtx, 'homedirOverride'>,-): Promise<void> {- try {- const dir = resolve(- okUserHomeDir(homeFor(ctx)),- 'edit-backups',- 'discarded',- discardedEditStashKey(documentName),- );- await tracedMkdir(dir, { recursive: true });- const stamp = new Date().toISOString().replace(/[:.]/g, '-');- await atomicWriteFile(resolve(dir, `${stamp}.md`), content, { fs: tracedAtomicFs });- const entries = readdirSync(dir).sort();- for (const old of entries.slice(0, Math.max(0, entries.length - DISCARDED_EDIT_STASH_MAX))) {- try {- tracedUnlinkSync(resolve(dir, old));- } catch {}- }- } catch (e) {- log.warn({ documentName, err: e }, 'discarded-edit stash failed');- }-}-async function backupExternalSkillOnce(filePath: string,ext: { name: string; rel: string | null },@@ -326,6 +323,176 @@ async function backupExternalSkillOnce(}}+function applyToLive(+ document: Y.Doc,+ documentName: string,+ ours: string,+ text: string,+ ctx: ManagedArtifactCtx,+): void {+ const detect = ctx.beforeReconcileDivergence?.(document, documentName, ours, text);+ document.transact(() => {+ applyDiskContentToDoc(document, text, undefined, documentName, undefined, detect);+ }, FILE_WATCHER_ORIGIN);+}++function agree(documentName: string, text: string, ctx: ManagedArtifactCtx): void {+ ctx.setReconciledBase(documentName, text);+ ctx.lkgCache.set(documentName, text);+}++class LiveMovedOnError extends Error {+ constructor(docName: string) {+ super(`the version of ${docName} here changed while the merge was being written`);+ this.name = 'LiveMovedOnError';+ }+}++type CheckedWrite = 'written' | 'moved' | 'unreadable';++async function writeChecked(+ filePath: string,+ documentName: string,+ text: string,+ observation: FileObservation | null,+ beforeCommit?: () => boolean,+): Promise<CheckedWrite> {+ try {+ await atomicWriteFile(filePath, text, {+ fs: tracedAtomicFs,+ beforeRename: () => {+ const restat = restatFile(filePath, observation);+ if (restat.kind === 'failed') throw new StoreRestatFailedError(documentName, restat.error);+ if (restat.kind === 'moved') throw new StoreRestatRefusedError(documentName);+ if (beforeCommit !== undefined && !beforeCommit()) throw new LiveMovedOnError(documentName);+ },+ });+ return 'written';+ } catch (err) {+ if (err instanceof StoreRestatRefusedError) {+ incrementStoreRestatRefused();+ return 'moved';+ }+ if (err instanceof LiveMovedOnError) return 'moved';+ if (err instanceof StoreRestatFailedError) return 'unreadable';+ throw err;+ }+}++type OutsideVersionResult = SettledMergeOutcome | SaveHold | 'retry';++type OutsideRead = Extract<ObservedTextRead, { kind: 'read' }>;++async function takeOutsideVersion(+ document: Y.Doc,+ documentName: string,+ disk: OutsideRead,+ filePath: string,+ ctx: ManagedArtifactCtx,+ site: 'store' | 'intake',+): Promise<OutsideVersionResult> {+ const reportSite = site === 'store' ? 'skill-store' : 'skill-intake';+ const settle = (outcome: SettledMergeOutcome): SettledMergeOutcome => {+ incrementManagedArtifactMerge(site, outcome);+ return outcome;+ };+ const hold = (held: SaveHold): SaveHold => {+ incrementManagedArtifactMerge(site, 'held');+ return held;+ };+ if (!disk.lossless) {+ log.info(+ { documentName },+ 'the file changed outside to bytes that are not valid UTF-8; nothing was applied or written so they stay on disk',+ );+ return hold(heldNotUtf8(filePath, disk.observation));+ }+ const ours = document.getText('source').toString();+ const base = ctx.getReconciledBase(documentName) ?? ctx.lkgCache.get(documentName) ?? '';+ if (ours === base) {+ applyToLive(document, documentName, ours, disk.text, ctx);+ agree(documentName, disk.text, ctx);+ return settle('applied');+ }+ const merge = reconcile({ docName: documentName, base, ours, theirs: disk.text });+ switch (merge.kind) {+ case 'noop':+ return settle('unchanged');+ case 'clean':+ applyToLive(document, documentName, ours, merge.newContent, ctx);+ agree(documentName, merge.newContent, ctx);+ return settle('applied');+ case 'merged':+ case 'both-kept': {+ const written = await writeChecked(+ filePath,+ documentName,+ merge.newContent,+ disk.observation,+ () => {+ if (document.getText('source').toString() !== ours) return false;+ applyToLive(document, documentName, ours, merge.newContent, ctx);+ return true;+ },+ );+ if (written === 'moved') return 'retry';+ if (written === 'unreadable') return hold(heldFor('unreadable'));+ agree(documentName, merge.newContent, ctx);+ if (merge.kind === 'merged') return settle('merged');+ ctx.history?.bothKept(documentName, { ours, theirs: disk.text }, merge.kept);+ reportReconcileBothKept(documentName, merge.kept, reportSite);+ return settle('both-kept');+ }+ case 'refused': {+ reportReconcileCheckFailed(documentName, merge, reportSite);+ const saved =+ ctx.history !== null &&+ (await ctx.history.keptLive(+ documentName,+ { side: 'theirs', bytes: disk.text },+ merge.reason,+ ));+ const backup = saved+ ? null+ : await backUpDisplacedVersion(homeFor(ctx), null, documentName, disk.text, 'SKILL.md');+ if (!saved && backup === null) {+ log.warn(+ { documentName, reason: merge.reason },+ 'the outside version could not be merged or kept in history or the backup folder; nothing was written so it stays on disk',+ );+ return hold(heldFor('no-history-or-backup'));+ }+ if (backup !== null) ctx.history?.noticeBackup(documentName, 'theirs', merge.reason, backup);+ const reread = readObservedText(filePath);+ if (reread.kind !== 'read' || reread.text !== disk.text) return 'retry';+ const written = await writeChecked(+ filePath,+ documentName,+ document.getText('source').toString(),+ reread.observation,+ );+ if (written === 'moved') return 'retry';+ if (written === 'unreadable') return hold(heldFor('unreadable'));+ agree(documentName, document.getText('source').toString(), ctx);+ if (saved) {+ reportReconcileKeptLive(documentName, merge.reason, reportSite);+ return settle('kept-live');+ }+ log.warn(+ { documentName, reason: merge.reason, backup: backup?.display },+ 'the outside version could not be merged or saved to history; it was kept in the backup folder and the version here stays',+ );+ return settle('stash-fallback');+ }+ default: {+ const unhandled: never = merge;+ throw new Error(`unhandled reconcile outcome: ${String(unhandled)}`);+ }+ }+}++const MAX_OUTSIDE_VERSIONS_PER_STORE = 3;+/** Serializes from `Y.Text('source')` (verbatim — precedent #38). */export async function storeManagedArtifactDoc(document: Y.Doc,@@ -343,9 +510,7 @@ export async function storeManagedArtifactDoc(if (lastTransactionOrigin === FILE_WATCHER_ORIGIN) return 'no-op';- const content = document.getText('source').toString();- const lkg = ctx.lkgCache.get(documentName);- if (content === lkg) return 'no-op';+ if (document.getText('source').toString() === ctx.lkgCache.get(documentName)) return 'no-op';const containerDir = managedArtifactContainerDir(documentName, ctx);if (containerDir === null) return 'no-op';@@ -363,35 +528,58 @@ export async function storeManagedArtifactDoc(await tracedMkdir(resolve(filePath, '..'), { recursive: true });if (extStore) await backupExternalSkillOnce(filePath, extStore, ctx);return await withFileLock(`${filePath}.lock`, async () => {- if (existsSync(filePath)) {- let disk: string | null = null;- try {- disk = readFileSync(filePath, 'utf-8');- } catch (readErr) {- if ((readErr as NodeJS.ErrnoException).code !== 'ENOENT') {- log.warn(- { documentName, err: readErr },- 'store: pre-write disk read failed (non-ENOENT); proceeding to write',- );- }- disk = null;+ for (let round = 0; round < MAX_OUTSIDE_VERSIONS_PER_STORE; round++) {+ const content = document.getText('source').toString();+ const lkg = ctx.lkgCache.get(documentName);+ if (content === lkg) return 'no-op';+ const disk = readObservedText(filePath);+ if (disk.kind === 'failed') {+ incrementManagedArtifactMerge('store', 'held');+ log.warn(+ { documentName, err: disk.error },+ 'store: the file could not be read for the compare before the write; nothing was written',+ );+ return heldFor('unreadable');}- if (disk !== null && disk !== lkg && disk !== content) {+ const base = ctx.getReconciledBase(documentName) ?? lkg;+ if (+ disk.kind === 'read' &&+ disk.text !== lkg &&+ disk.text !== base &&+ disk.text !== content+ ) {incrementManagedArtifactReconcile();- const detect = ctx.beforeReconcileDivergence?.(document, documentName, content, disk);- await stashDiscardedEdit(documentName, content, ctx);- document.transact(() => {- applyDiskContentToDoc(document, disk, undefined, documentName, undefined, detect);- }, FILE_WATCHER_ORIGIN);- ctx.setReconciledBase(documentName, disk);- ctx.lkgCache.set(documentName, disk);- return 'reconciled';+ const outcome = await takeOutsideVersion(+ document,+ documentName,+ disk,+ filePath,+ ctx,+ 'store',+ );+ if (outcome === 'retry') continue;+ return outcome;}+ const written = await writeChecked(+ filePath,+ documentName,+ content,+ disk.kind === 'read' ? disk.observation : null,+ );+ if (written === 'moved') continue;+ if (written === 'unreadable') {+ incrementManagedArtifactMerge('store', 'held');+ return heldFor('unreadable');+ }+ agree(documentName, content, ctx);+ return 'persisted';}- await atomicWriteFile(filePath, content, { fs: tracedAtomicFs });- ctx.lkgCache.set(documentName, content);- ctx.setReconciledBase(documentName, content);- return 'persisted';+ incrementManagedArtifactMerge('store', 'held');+ log.warn(+ { documentName, rounds: MAX_OUTSIDE_VERSIONS_PER_STORE },+ 'store: the file kept changing outside while it was being saved; nothing more was written',+ );+ return heldFor('keeps-changing');});} catch (e) {if (e instanceof FileLockTimeoutError) {@@ -403,21 +591,44 @@ export async function storeManagedArtifactDoc(}}-export type ApplyExternalManagedArtifactChangeOutcome = 'applied' | 'no-op';+export type ApplyExternalManagedArtifactChangeOutcome = 'no-op' | ManagedArtifactMergeOutcome;-export function applyExternalManagedArtifactChange(+export async function applyExternalManagedArtifactChange(document: Y.Doc | null,documentName: string,raw: string,ctx: ManagedArtifactCtx,-): ApplyExternalManagedArtifactChangeOutcome {+): Promise<ApplyExternalManagedArtifactChangeOutcome> {if (!document) return 'no-op';const lkg = ctx.lkgCache.get(documentName);if (lkg !== undefined && lkg === raw) return 'no-op';- document.transact(() => {- applyDiskContentToDoc(document, raw, undefined, documentName);- }, FILE_WATCHER_ORIGIN);- ctx.setReconciledBase(documentName, raw);- ctx.lkgCache.set(documentName, raw);- return 'applied';+ if (document.getText('source').toString() === raw) {+ agree(documentName, raw, ctx);+ return 'no-op';+ }+ const filePath = managedArtifactAbsPath(documentName, ctx);+ try {+ return await withFileLock(`${filePath}.lock`, async () => {+ const disk = readObservedText(filePath);+ if (disk.kind !== 'read' || disk.text !== raw) return 'no-op';+ const outcome = await takeOutsideVersion(+ document,+ documentName,+ disk,+ filePath,+ ctx,+ 'intake',+ );+ if (outcome === 'retry') return 'no-op';+ return typeof outcome === 'object' ? 'held' : outcome;+ });+ } catch (e) {+ if (!(e instanceof FileLockTimeoutError)) throw e;+ incrementManagedArtifactMerge('intake', 'held');+ log.warn(+ { documentName, err: e },+ 'intake: the file lock timed out, so the outside change was not taken in; the next save compares it',+ );+ return 'held';+ }}diff --git a/packages/server/src/managed-artifact-watcher.test.ts b/packages/server/src/managed-artifact-watcher.test.tsindex bc3096e5d..98fccc5cc 100644--- a/packages/server/src/managed-artifact-watcher.test.ts+++ b/packages/server/src/managed-artifact-watcher.test.ts@@ -25,7 +25,9 @@ describe('startManagedArtifactWatcher', () => {test('fires onChange for a SKILL.md created after start', async () => {const skillsRoot = resolve(root, '.ok', 'skills');const seen: Array<[string, string]> = [];- cleanup = await startManagedArtifactWatcher([skillsRoot], (p, c) => seen.push([p, c]));+ cleanup = await startManagedArtifactWatcher([skillsRoot], (p, c) => {+ seen.push([p, c]);+ });const skillDir = resolve(skillsRoot, 'demo');mkdirSync(skillDir, { recursive: true });@@ -51,7 +53,9 @@ describe('startManagedArtifactWatcher', () => {const unlinked: string[] = [];cleanup = await startManagedArtifactWatcher([skillsRoot],- (p) => changed.push(p),+ (p) => {+ changed.push(p);+ },(p) => unlinked.push(p),);@@ -73,7 +77,9 @@ describe('startManagedArtifactWatcher', () => {writeFileSync(leaf, 'v1', 'utf-8');const contents: string[] = [];- cleanup = await startManagedArtifactWatcher([skillsRoot], (_p, c) => contents.push(c));+ cleanup = await startManagedArtifactWatcher([skillsRoot], (_p, c) => {+ contents.push(c);+ });writeFileSync(resolve(skillDir, 'NOTES.md'), 'noise', 'utf-8');writeFileSync(leaf, 'v2', 'utf-8');@@ -94,7 +100,9 @@ describe('startManagedArtifactWatcher', () => {writeFileSync(leaf, 'v1', 'utf-8');const seen: Array<[string, string]> = [];- cleanup = await startManagedArtifactWatcher([skillsRoot], (p, c) => seen.push([p, c]));+ cleanup = await startManagedArtifactWatcher([skillsRoot], (p, c) => {+ seen.push([p, c]);+ });const addedDir = resolve(skillsRoot, 'added');mkdirSync(addedDir, { recursive: true });@@ -129,6 +137,7 @@ describe('managed-artifact watch roots never conjure a harness home', () => {lkgCache: new Map<string, string>(),setReconciledBase: () => {},getReconciledBase: () => undefined,+ history: null,}),() => {},);diff --git a/packages/server/src/managed-artifact-watcher.ts b/packages/server/src/managed-artifact-watcher.tsindex 4c9a01139..afd34460b 100644--- a/packages/server/src/managed-artifact-watcher.ts+++ b/packages/server/src/managed-artifact-watcher.ts@@ -10,7 +10,7 @@ export type ManagedArtifactWatcherUnsubscribe = () => Promise<void>;export async function startManagedArtifactWatcher(roots: ReadonlyArray<string>,- onChange: (absPath: string, content: string) => void,+ onChange: (absPath: string, content: string) => void | Promise<void>,onUnlink?: (absPath: string) => void,): Promise<ManagedArtifactWatcherUnsubscribe> {const log = getLogger('managed-artifact-watcher');@@ -44,10 +44,13 @@ export async function startManagedArtifactWatcher(}if (content === lastContent.get(path)) return;lastContent.set(path, content);+ const reportFailure = (err: unknown): void => {+ log.warn({ err, path }, 'managed-artifact change handler threw');+ };try {- onChange(path, content);+ void Promise.resolve(onChange(path, content)).catch(reportFailure);} catch (err) {- log.warn({ err, path }, 'managed-artifact change handler threw');+ reportFailure(err);}};const handleUnlink = (path: string): void => {diff --git a/packages/server/src/merge-history.test.ts b/packages/server/src/merge-history.test.tsindex 8b48ca7f8..0321090f0 100644--- a/packages/server/src/merge-history.test.ts+++ b/packages/server/src/merge-history.test.ts@@ -1,4 +1,4 @@-import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { parseCheckpoint } from '@inkeep/open-knowledge-core/shadow-repo-layout';@@ -6,7 +6,7 @@ import simpleGit from 'simple-git';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';import { DocNoticeLedger } from './doc-notices.ts';-import { createMergeHistoryRecorder } from './merge-history.ts';+import { createMergeHistoryRecorder, keepNoEngineVersion } from './merge-history.ts';import { getMetrics, resetMetrics } from './metrics.ts';import type { KeptBlockPair } from './reconciliation.ts';import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';@@ -113,6 +113,192 @@ describe('createMergeHistoryRecorder', () => {expect(getMetrics().mergeHistoryCheckpointFailures).toBe(0);});+ test('an outside version of a file with no merge engine lands in its own kind and counters, with full bytes', async () => {+ const projectRoot = join(tmpDir, 'project');+ mkdirSync(projectRoot, { recursive: true });+ await simpleGit(projectRoot).init();+ configureTestGitRepository(projectRoot);+ const shadow = await initShadowRepo(projectRoot);+ const outside = '{"type":"excalidraw","elements":[]}\n';++ await expect(+ recorderFor(shadow).saveNoEngine(+ 'board.excalidraw',+ { side: 'theirs', bytes: outside },+ 'excalidraw',+ ),+ ).resolves.toMatch(/^[0-9a-f]{40}$/);++ const sg = shadowGit(shadow);+ const sha = (+ await sg.raw('for-each-ref', '--format=%(objectname)', 'refs/checkpoints/main/')+ ).trim();+ expect(parseCheckpoint(await sg.raw('log', '-1', '--format=%B', sha))).toMatchObject({+ kind: 'external-change-no-engine',+ docName: 'board.excalidraw',+ metadata: { side: 'theirs', fileType: 'excalidraw' },+ });+ expect(await sg.raw('show', `${sha}:board.excalidraw`)).toBe(outside);+ expect(getMetrics().noEngineHistoryCheckpointCreated).toBe(1);+ expect(getMetrics().mergeHistoryCheckpointCreated).toBe(0);+ });++ test('a no-engine write with no shadow repo or a failing write resolves null', async () => {+ await expect(+ recorderFor(undefined).saveNoEngine('flow.mmd', { side: 'theirs', bytes: 'x\n' }, 'mermaid'),+ ).resolves.toBeNull();+ await expect(+ recorderFor({ gitDir: join(tmpDir, 'missing-git-dir'), workTree: tmpDir }).saveNoEngine(+ 'flow.mmd',+ { side: 'theirs', bytes: 'x\n' },+ 'mermaid',+ ),+ ).resolves.toBeNull();+ expect(getMetrics().mergeHistoryUnavailable).toBe(1);+ expect(getMetrics().noEngineHistoryCheckpointFailures).toBe(1);+ expect(getMetrics().noEngineHistoryCheckpointCreated).toBe(0);+ });++ test('a displaced settings edit and a refused outside settings file get their own notice reasons, naming history or the backup', async () => {+ const recorded: Array<{+ docName: string;+ kind: string;+ side: string;+ reason: string;+ at: string;+ }> = [];+ const history = createMergeHistoryRecorder({+ getShadow: () => ({ gitDir: tmpDir, workTree: tmpDir }),+ contentRoot: '',+ getBranch: () => 'main',+ writeCheckpoint: async () => 'd'.repeat(40),+ notices: {+ record: (docName, _branch, event) => {+ if (event.kind === 'moved-to-history') {+ recorded.push({+ docName,+ kind: event.kind,+ side: event.side,+ reason: event.reason,+ at: event.entry,+ });+ }+ if (event.kind === 'moved-to-backup') {+ recorded.push({+ docName,+ kind: event.kind,+ side: event.side,+ reason: event.reason,+ at: event.backup,+ });+ }+ return 'notice';+ },+ attachEntry: () => {},+ withdrawHeld: () => {},+ },+ });+ const entry = 'd'.repeat(40);+ const backup = {+ abs: '/home/me/.ok/edit-backups/discarded/flow.mmd/x.mmd',+ display: '~/.ok/edit-backups/discarded/flow.mmd/x.mmd',+ };++ history.noticeNoEngine('__config__/project', 'ours', 'config', { where: 'history', entry });+ history.noticeNoEngine('__config__/project', 'theirs', 'config', { where: 'history', entry });+ history.noticeNoEngine('flow.mmd', 'theirs', 'mermaid', { where: 'history', entry });+ history.noticeNoEngine('flow.mmd', 'theirs', 'mermaid', { where: 'backup', backup });++ expect(recorded).toEqual([+ {+ docName: '__config__/project',+ kind: 'moved-to-history',+ side: 'ours',+ reason: 'outside-settings-applied',+ at: entry,+ },+ {+ docName: '__config__/project',+ kind: 'moved-to-history',+ side: 'theirs',+ reason: 'outside-settings-invalid',+ at: entry,+ },+ {+ docName: 'flow.mmd',+ kind: 'moved-to-history',+ side: 'theirs',+ reason: 'no-merge-engine',+ at: entry,+ },+ {+ docName: 'flow.mmd',+ kind: 'moved-to-backup',+ side: 'theirs',+ reason: 'no-merge-engine',+ at: backup.display,+ },+ ]);+ });++ test('a no-engine version goes to history when it can, else to the backup folder, else nowhere', async () => {+ const home = join(tmpDir, 'home');+ mkdirSync(home, { recursive: true });+ const displaced = { side: 'theirs' as const, bytes: 'graph LR\n' };+ const saving = createMergeHistoryRecorder({+ getShadow: () => ({ gitDir: tmpDir, workTree: tmpDir }),+ contentRoot: '',+ getBranch: () => 'main',+ writeCheckpoint: async () => 'e'.repeat(40),+ });++ await expect(+ keepNoEngineVersion(+ saving,+ home,+ '/projects/one',+ 'flow.mmd',+ displaced,+ 'mermaid',+ 'flow.mmd',+ ),+ ).resolves.toEqual({ where: 'history', entry: 'e'.repeat(40) });++ const kept = await keepNoEngineVersion(+ recorderFor(undefined),+ home,+ '/projects/one',+ 'flow.mmd',+ displaced,+ 'mermaid',+ 'flow.mmd',+ );+ expect(kept).toMatchObject({+ where: 'backup',+ backup: {+ display: expect.stringMatching(+ /^~\/\.ok\/edit-backups\/discarded\/projects\/[0-9a-f]+\/flow\.mmd\/.+\.mmd$/,+ ),+ },+ });+ expect(kept?.where === 'backup' && readFileSync(kept.backup.abs, 'utf-8')).toBe('graph LR\n');++ writeFileSync(join(tmpDir, 'not-a-home'), 'file');+ await expect(+ keepNoEngineVersion(+ null,+ join(tmpDir, 'not-a-home'),+ '/projects/one',+ 'flow.mmd',+ displaced,+ 'mermaid',+ 'flow.mmd',+ ),+ ).resolves.toBeNull();+ expect(getMetrics().displacedVersionBackups).toBe(1);+ expect(getMetrics().displacedVersionBackupFailures).toBe(1);+ });+describe('the notice on the document', () => {function noticesIn(dir: string): DocNoticeLedger {writeFileSync(join(dir, 'doc.md'), '# Doc\n');@@ -176,6 +362,82 @@ describe('createMergeHistoryRecorder', () => {expect([...(notice?.entries ?? [])].sort()).toEqual([...shas].sort());});+ test('a no-engine event raises a moved-to-history notice naming its entry once the entry exists', async () => {+ const projectRoot = join(tmpDir, 'project');+ mkdirSync(projectRoot, { recursive: true });+ await simpleGit(projectRoot).init();+ configureTestGitRepository(projectRoot);+ const shadow = await initShadowRepo(projectRoot);+ writeFileSync(join(projectRoot, 'flow.mmd'), 'graph TD\n');+ const notices = new DocNoticeLedger({+ projectDir: projectRoot,+ contentDir: projectRoot,+ getShadow: () => shadow,+ isReady: () => true,+ signal: () => {},+ });++ const history = createMergeHistoryRecorder({+ getShadow: () => shadow,+ contentRoot: '',+ getBranch: () => 'main',+ notices,+ });+ const copy = await keepNoEngineVersion(+ history,+ tmpDir,+ projectRoot,+ 'flow.mmd',+ { side: 'theirs', bytes: 'graph LR\n' },+ 'mermaid',+ 'flow.mmd',+ );+ if (copy === null) throw new Error('expected the version to reach history');+ history.noticeNoEngine('flow.mmd', 'theirs', 'mermaid', copy);++ const sha = (+ await shadowGit(shadow).raw(+ 'for-each-ref',+ '--format=%(objectname)',+ 'refs/checkpoints/main/',+ )+ ).trim();+ expect(await notices.list('main')).toEqual([+ expect.objectContaining({+ docName: 'flow.mmd',+ file: 'flow.mmd',+ kind: 'moved-to-history',+ side: 'theirs',+ reason: 'no-merge-engine',+ entries: [sha],+ }),+ ]);+ });++ test('a held save raises its notice with the cause, and only a held notice is withdrawn when the save lands', async () => {+ const notices = noticesIn(tmpDir);+ const history = createMergeHistoryRecorder({+ getShadow: () => undefined,+ contentRoot: '',+ getBranch: () => 'main',+ notices,+ });++ history.noticeHeld('doc', 'not-utf8');+ expect(await notices.list('main')).toEqual([+ expect.objectContaining({ docName: 'doc', kind: 'save-held', cause: 'not-utf8' }),+ ]);++ history.clearHeld('doc');+ expect(await notices.list('main')).toEqual([]);++ history.bothKept('doc', { ours: 'here\n', theirs: 'outside\n' }, [KEPT_TWICE]);+ history.clearHeld('doc');+ expect(await notices.list('main')).toEqual([+ expect.objectContaining({ docName: 'doc', kind: 'both-kept' }),+ ]);+ });+test('a kept-live refusal raises its notice only when the outside version reached history', async () => {const failing = noticesIn(tmpDir);await createMergeHistoryRecorder({diff --git a/packages/server/src/merge-history.ts b/packages/server/src/merge-history.tsindex b7c64d992..a2de6f038 100644--- a/packages/server/src/merge-history.ts+++ b/packages/server/src/merge-history.ts@@ -1,12 +1,16 @@import type { ParsedCheckpoint } from '@inkeep/open-knowledge-core/shadow-repo-layout';-import type { DocNoticeSink } from './doc-notices.ts';+import type { DocNoticeSink, MoveReason } from './doc-notices.ts';+import { type BackupCopy, backUpDisplacedVersion } from './edit-backups.ts';import { getLogger } from './logger.ts';import {incrementMergeHistoryCheckpointCreated,incrementMergeHistoryCheckpointFailures,incrementMergeHistoryUnavailable,+ incrementNoEngineHistoryCheckpointCreated,+ incrementNoEngineHistoryCheckpointFailures,} from './metrics.ts';import { countKeptBlocks, type KeptBlockPair } from './reconciliation.ts';+import type { VisibleHoldCause } from './save-hold.ts';import {type InMemoryCheckpointParams,type ShadowHandle,@@ -20,9 +24,20 @@ type KeptLiveMetadata = Extract<type MergeSide = KeptLiveMetadata['side'];+type NoEngineFileType = Extract<+ ParsedCheckpoint,+ { kind: 'external-change-no-engine' }+>['metadata']['fileType'];++export type EnginelessFileType = Exclude<NoEngineFileType, 'config'>;++export type KeptCopy =+ | { readonly where: 'history'; readonly entry: string }+ | { readonly where: 'backup'; readonly backup: BackupCopy };+type MergeHistoryParams = Extract<InMemoryCheckpointParams,- { kind: 'external-change-both-kept' | 'external-change-kept-live' }+ { kind: 'external-change-both-kept' | 'external-change-kept-live' | 'external-change-no-engine' }>;export interface MergeHistoryRecorder {@@ -36,6 +51,20 @@ export interface MergeHistoryRecorder {displaced: { side: MergeSide; bytes: string },reason: KeptLiveMetadata['reason'],): Promise<boolean>;+ saveNoEngine(+ docName: string,+ displaced: { side: MergeSide; bytes: string },+ fileType: NoEngineFileType,+ ): Promise<string | null>;+ noticeNoEngine(+ docName: string,+ side: MergeSide,+ fileType: NoEngineFileType,+ copy: KeptCopy,+ ): void;+ noticeBackup(docName: string, side: MergeSide, reason: MoveReason, backup: BackupCopy): void;+ noticeHeld(docName: string, cause: VisibleHoldCause): void;+ clearHeld(docName: string): void;}export type MergeHistoryWriter = typeof saveInMemoryCheckpoint;@@ -55,6 +84,35 @@ const SIDE_LABEL: Record<MergeSide, string> = {theirs: 'Outside version',};+function noEngineNoticeReason(+ fileType: NoEngineFileType,+ side: MergeSide,+): Extract<+ MoveReason,+ 'no-merge-engine' | 'outside-settings-applied' | 'outside-settings-invalid'+> {+ if (fileType !== 'config') return 'no-merge-engine';+ return side === 'ours' ? 'outside-settings-applied' : 'outside-settings-invalid';+}++const HISTORY_COUNTERS: Record<+ MergeHistoryParams['kind'],+ { created: () => void; failed: () => void }+> = {+ 'external-change-both-kept': {+ created: incrementMergeHistoryCheckpointCreated,+ failed: incrementMergeHistoryCheckpointFailures,+ },+ 'external-change-kept-live': {+ created: incrementMergeHistoryCheckpointCreated,+ failed: incrementMergeHistoryCheckpointFailures,+ },+ 'external-change-no-engine': {+ created: incrementNoEngineHistoryCheckpointCreated,+ failed: incrementNoEngineHistoryCheckpointFailures,+ },+};+export function createMergeHistoryRecorder(options: MergeHistoryRecorderOptions,): MergeHistoryRecorder {@@ -62,7 +120,7 @@ export function createMergeHistoryRecorder(const write = (shadow: ShadowHandle, params: MergeHistoryParams): Promise<string | null> =>writeCheckpoint(shadow, options.contentRoot, params).then((sha) => {- incrementMergeHistoryCheckpointCreated();+ HISTORY_COUNTERS[params.kind].created();log.info({ docName: params.docName, kind: params.kind, side: params.metadata.side, sha },`[reconcile] history entry saved (${params.kind}, ${params.metadata.side}): ${params.docName}`,@@ -70,7 +128,7 @@ export function createMergeHistoryRecorder(return sha;},(err: unknown) => {- incrementMergeHistoryCheckpointFailures();+ HISTORY_COUNTERS[params.kind].failed();log.error({ err, docName: params.docName, kind: params.kind, side: params.metadata.side },`[reconcile] history entry write failed (${params.kind}, ${params.metadata.side}): ${params.docName}`,@@ -87,6 +145,54 @@ export function createMergeHistoryRecorder();};+ const saveNoEngine: MergeHistoryRecorder['saveNoEngine'] = async (+ docName,+ displaced,+ fileType,+ ) => {+ const shadow = options.getShadow();+ if (!shadow) {+ unavailable(docName, 'external-change-no-engine');+ return null;+ }+ return write(shadow, {+ kind: 'external-change-no-engine',+ docName,+ contents: displaced.bytes,+ label: `${SIDE_LABEL[displaced.side]} moved to history (no merge for ${fileType}) @ ${new Date().toISOString()}`,+ branch: options.getBranch() ?? 'main',+ metadata: { side: displaced.side, fileType },+ });+ };++ const noticeBackup: MergeHistoryRecorder['noticeBackup'] = (docName, side, reason, backup) => {+ options.notices?.record(docName, options.getBranch() ?? 'main', {+ kind: 'moved-to-backup',+ side,+ reason,+ backup: backup.display,+ });+ };++ const noticeNoEngine: MergeHistoryRecorder['noticeNoEngine'] = (+ docName,+ side,+ fileType,+ copy,+ ) => {+ const reason = noEngineNoticeReason(fileType, side);+ if (copy.where === 'backup') {+ noticeBackup(docName, side, reason, copy.backup);+ return;+ }+ options.notices?.record(docName, options.getBranch() ?? 'main', {+ kind: 'moved-to-history',+ side,+ reason,+ entry: copy.entry,+ });+ };+return {bothKept(docName, versions, kept) {const counts = countKeptBlocks(kept);@@ -142,5 +248,32 @@ export function createMergeHistoryRecorder(});return true;},++ saveNoEngine,+ noticeNoEngine,+ noticeBackup,++ noticeHeld(docName, cause) {+ options.notices?.record(docName, options.getBranch() ?? 'main', { kind: 'save-held', cause });+ },++ clearHeld(docName) {+ options.notices?.withdrawHeld(docName, options.getBranch() ?? 'main');+ },};}++export async function keepNoEngineVersion(+ history: Pick<MergeHistoryRecorder, 'saveNoEngine'> | null,+ home: string,+ project: string,+ docName: string,+ displaced: { side: MergeSide; bytes: string },+ fileType: NoEngineFileType,+ fileName: string,+): Promise<KeptCopy | null> {+ const entry = history === null ? null : await history.saveNoEngine(docName, displaced, fileType);+ if (entry !== null) return { where: 'history', entry };+ const backup = await backUpDisplacedVersion(home, project, docName, displaced.bytes, fileName);+ return backup === null ? null : { where: 'backup', backup };+}diff --git a/packages/server/src/mermaid-persistence.test.ts b/packages/server/src/mermaid-persistence.test.tsindex 6b699ee8b..eb366ee0f 100644--- a/packages/server/src/mermaid-persistence.test.ts+++ b/packages/server/src/mermaid-persistence.test.ts@@ -1,22 +1,100 @@-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from 'node:fs';import { tmpdir } from 'node:os';import { dirname, join, resolve } from 'node:path';-import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';+import { fnv1aDigest, LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import * as Y from 'yjs';+import { DiskReceiptLog } from './disk-receipts.ts';+import * as fsTraced from './fs-traced.ts';import { tracedAtomicFs } from './fs-traced.ts';+import type { EnginelessFileType, KeptCopy } from './merge-history.ts';import {+ applyExternalEnginelessChange,loadMermaidDoc,MERMAID_SOURCE_ORIGIN,type MermaidPersistenceCtx,storeMermaidDoc,} from './mermaid-persistence.ts';+import { getMetrics, resetMetrics } from './metrics.ts';import { assertServerContentPath, snapshotServerContentScope } from './server-content-policy.ts';+import { contentHash } from './version-hash.ts';let contentDir: string;+let home: string;++interface MovedVersion {+ docName: string;+ side: 'ours' | 'theirs';+ bytes: string;+ fileType: string;+}-function makeCtx(): MermaidPersistenceCtx {- return { contentDir, lkgCache: new Map<string, string>() };+interface RecordedNotice {+ docName: string;+ side: 'ours' | 'theirs';+ fileType: string;+ copy: KeptCopy;+}++type RecordingCtx = MermaidPersistenceCtx & {+ receipts: DiskReceiptLog;+ moved: MovedVersion[];+ notices: RecordedNotice[];+};++function makeCtx(+ options: { historySaves?: boolean; noHistory?: boolean; duringSave?: () => void } = {},+): RecordingCtx {+ const moved: MovedVersion[] = [];+ const notices: RecordedNotice[] = [];+ return {+ contentDir,+ home,+ lkgCache: new Map<string, string>(),+ receipts: new DiskReceiptLog(),+ moved,+ notices,+ history: options.noHistory+ ? null+ : {+ saveNoEngine: async (docName, displaced, fileType) => {+ options.duringSave?.();+ if (options.historySaves === false) return null;+ moved.push({ docName, ...displaced, fileType });+ return `entry-${moved.length}`;+ },+ noticeNoEngine: (docName, side, fileType, copy) => {+ notices.push({ docName, side, fileType, copy });+ },+ },+ };+}++function backupsFor(docName: string): string[] {+ const dir = join(+ home,+ '.ok',+ 'edit-backups',+ 'discarded',+ 'projects',+ fnv1aDigest(contentDir),+ docName.replace(/[^A-Za-z0-9._-]+/g, '__'),+ );+ if (!existsSync(dir)) return [];+ return readdirSync(dir).map((name) => readFileSync(join(dir, name), 'utf-8'));+}++function blockBackups(): void {+ mkdirSync(join(home, '.ok'), { recursive: true });+ writeFileSync(join(home, '.ok', 'edit-backups'), 'not a folder');}const DOC = 'assets/flow.mmd';@@ -30,9 +108,13 @@ function writeMmd(content: string): void {beforeEach(() => {contentDir = mkdtempSync(join(tmpdir(), 'ok-mermaid-'));+ home = mkdtempSync(join(tmpdir(), 'ok-mermaid-home-'));+ resetMetrics();});afterEach(() => {+ vi.restoreAllMocks();rmSync(contentDir, { recursive: true, force: true });+ rmSync(home, { recursive: true, force: true });});describe('storeMermaidDoc', () => {@@ -95,24 +177,338 @@ describe('storeMermaidDoc', () => {expect(await storeMermaidDoc(doc, DOC, 'agent', ctx)).toBe('no-op');});- test('reconciles (imports disk) instead of clobbering when an external writer diverged from LKG', async () => {+ test('records an own-write receipt for the bytes it wrote', async () => {const ctx = makeCtx();const doc = new Y.Doc();doc.transact(() => doc.getText('source').insert(0, SRC), 'agent');expect(await storeMermaidDoc(doc, DOC, 'agent', ctx)).toBe('persisted');+ expect(ctx.receipts.get(DOC)).toMatchObject({ hash: contentHash(SRC), via: 'own-write' });+ expect(ctx.receipts.isRecentOwnWrite(DOC, contentHash(SRC))).toBe(true);+ });++ test('writes when disk still holds the last saved version though the receipt moved on', async () => {+ writeMmd(SRC);+ const ctx = makeCtx();+ const doc = new Y.Doc();+ loadMermaidDoc(doc, DOC, ctx);+ ctx.receipts.recordAgreed(DOC, 'graph TD; Elsewhere;\n');+ doc.transact(() => doc.getText('source').insert(0, '%% edited\n'), 'agent');+ expect(await storeMermaidDoc(doc, DOC, 'agent', ctx)).toBe('persisted');+ expect(readFileSync(ABS(), 'utf-8')).toBe(`%% edited\n${SRC}`);+ expect(ctx.moved).toEqual([]);+ });+});++const ENGINELESS_CASES: ReadonlyArray<{+ docName: string;+ fileType: EnginelessFileType;+ saved: string;+ here: string;+ outside: string;+}> = [+ {+ docName: 'diagrams/flow.mmd',+ fileType: 'mermaid',+ saved: 'graph TD\n A-->B\n',+ here: 'graph TD\n A-->C\n',+ outside: 'graph TD\n A-->D\n',+ },+ {+ docName: 'boards/plan.excalidraw',+ fileType: 'excalidraw',+ saved: '{"type":"excalidraw","elements":[{"id":"a","x":0}]}\n',+ here: '{"type":"excalidraw","elements":[{"id":"a","x":10}]}\n',+ outside: '{"type":"excalidraw","elements":[{"id":"a","x":20}]}\n',+ },+ {+ docName: 'src/value.ts',+ fileType: 'text',+ saved: 'export const value = 1;\n',+ here: 'export const value = 2;\n',+ outside: 'export const value = 3;\n',+ },+];++function writeDocFile(docName: string, content: string): void {+ const abs = resolve(contentDir, docName);+ mkdirSync(dirname(abs), { recursive: true });+ writeFileSync(abs, content, 'utf-8');+}++function readDocFile(docName: string): string {+ return readFileSync(resolve(contentDir, docName), 'utf-8');+}++function editTo(doc: Y.Doc, text: string): void {+ doc.transact(() => {+ const ytext = doc.getText('source');+ ytext.delete(0, ytext.length);+ ytext.insert(0, text);+ }, 'person');+}++function openWithUnsavedEdit(+ kase: (typeof ENGINELESS_CASES)[number],+ ctx: RecordingCtx,+): { doc: Y.Doc; undo: Y.UndoManager } {+ writeDocFile(kase.docName, kase.saved);+ const doc = new Y.Doc();+ loadMermaidDoc(doc, kase.docName, ctx);+ const undo = new Y.UndoManager(doc.getText('source'), { trackedOrigins: new Set(['person']) });+ editTo(doc, kase.here);+ return { doc, undo };+}++describe.each(ENGINELESS_CASES)('an outside write under unsaved edits to $docName', (kase) => {+ test('keeps the version here live and on disk and moves the outside version to history', async () => {+ const ctx = makeCtx();+ const { doc, undo } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('kept-live');++ expect(doc.getText('source').toString()).toBe(kase.here);+ expect(readDocFile(kase.docName)).toBe(kase.here);+ expect(ctx.moved).toEqual([+ { docName: kase.docName, side: 'theirs', bytes: kase.outside, fileType: kase.fileType },+ ]);+ expect(ctx.notices).toEqual([+ {+ docName: kase.docName,+ side: 'theirs',+ fileType: kase.fileType,+ copy: { where: 'history', entry: 'entry-1' },+ },+ ]);+ expect(backupsFor(kase.docName)).toEqual([]);+ expect(ctx.lkgCache.get(kase.docName)).toBe(kase.here);+ expect(ctx.receipts.get(kase.docName)?.hash).toBe(contentHash(kase.here));+ expect(getMetrics().enginelessStore).toEqual({ 'kept-live': 1 });+ expect(undo.undoStack).toHaveLength(1);+ undo.undo();+ expect(doc.getText('source').toString()).toBe(kase.saved);+ });++ test('when history cannot take the outside version it goes to the backup folder and the edits are written', async () => {+ const ctx = makeCtx({ historySaves: false });+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('kept-live');++ expect(doc.getText('source').toString()).toBe(kase.here);+ expect(readDocFile(kase.docName)).toBe(kase.here);+ expect(backupsFor(kase.docName)).toEqual([kase.outside]);+ expect(ctx.notices).toHaveLength(1);+ const [notice] = ctx.notices;+ expect(notice?.copy.where).toBe('backup');+ expect(notice?.copy.where === 'backup' && notice.copy.backup.display).toMatch(+ /^~\/\.ok\/edit-backups\/discarded\/projects\/[0-9a-f]{8}\/.+/,+ );+ expect(getMetrics().displacedVersionBackups).toBe(1);+ });++ test('writes nothing and keeps the version here live when neither history nor the backup folder can take the outside version', async () => {+ blockBackups();+ const ctx = makeCtx({ historySaves: false });+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toEqual({+ kind: 'held',+ cause: 'no-history-or-backup',+ });++ expect(doc.getText('source').toString()).toBe(kase.here);+ expect(readDocFile(kase.docName)).toBe(kase.outside);+ expect(ctx.lkgCache.get(kase.docName)).toBe(kase.saved);+ expect(ctx.notices).toEqual([]);+ expect(getMetrics().enginelessStore).toEqual({ 'held-no-history-or-backup': 1 });+ expect(getMetrics().displacedVersionBackupFailures).toBe(1);+ });+});++describe('the compare read before an engine-less write', () => {+ test('a persistence with no history recorder keeps the outside version in the backup folder before writing', async () => {+ const kase = ENGINELESS_CASES[0];+ const ctx = makeCtx({ noHistory: true });+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('kept-live');+ expect(readDocFile(kase.docName)).toBe(kase.here);+ expect(backupsFor(kase.docName)).toEqual([kase.outside]);+ });++ test('a persistence with no history recorder and no backup folder never writes over an outside change', async () => {+ blockBackups();+ const kase = ENGINELESS_CASES[0];+ const ctx = makeCtx({ noHistory: true });+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toEqual({+ kind: 'held',+ cause: 'no-history-or-backup',+ });+ expect(readDocFile(kase.docName)).toBe(kase.outside);+ });++ test('retries a busy read, then writes nothing when the file stays unreadable', async () => {+ const kase = ENGINELESS_CASES[0];+ const ctx = makeCtx();+ const { doc } = openWithUnsavedEdit(kase, ctx);+ vi.spyOn(fsTraced, 'tracedReadObservedSync').mockImplementation(() => {+ throw Object.assign(new Error('busy'), { code: 'EBUSY' });+ });- const external = 'sequenceDiagram; Alice->>Bob: Hi;\n';- writeMmd(external);+ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toEqual({+ kind: 'held',+ cause: 'unreadable',+ });- doc.transact(() => {- const yt = doc.getText('source');- yt.delete(0, yt.length);- yt.insert(0, 'graph TD; X-->Y;\n');- }, 'agent');- expect(await storeMermaidDoc(doc, DOC, 'agent', ctx)).toBe('reconciled');- expect(doc.getText('source').toString()).toBe(external);- expect(readFileSync(ABS(), 'utf-8')).toBe(external);- expect(ctx.lkgCache.get(DOC)).toBe(external);+ vi.restoreAllMocks();+ expect(readDocFile(kase.docName)).toBe(kase.saved);+ expect(getMetrics().enginelessStore).toEqual({ 'held-unreadable': 1 });+ expect(getMetrics().storeDiskCompareReadRetries).toBe(3);+ });+});++describe('an outside write that lands while an engine-less save runs', () => {+ test('a write during the history save is also moved to history before the edits are written', async () => {+ const kase = ENGINELESS_CASES[0];+ const later = 'graph TD\n A-->E\n';+ let planted = false;+ const ctx = makeCtx({+ duringSave: () => {+ if (planted) return;+ planted = true;+ writeDocFile(kase.docName, later);+ },+ });+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('kept-live');++ expect(readDocFile(kase.docName)).toBe(kase.here);+ expect(ctx.moved.map((version) => version.bytes)).toEqual([kase.outside, later]);+ });++ test('a write between the compare and the rename is refused, moved to history, and the edits land after it', async () => {+ const kase = ENGINELESS_CASES[2];+ const ctx = makeCtx();+ const { doc } = openWithUnsavedEdit(kase, ctx);+ const between = 'export const value = 44;\n';+ const write = tracedAtomicFs.writeFile;+ let planted = false;+ vi.spyOn(tracedAtomicFs, 'writeFile').mockImplementation(async (...args) => {+ await write(...args);+ if (planted) return;+ planted = true;+ writeDocFile(kase.docName, between);+ });++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('kept-live');++ expect(readDocFile(kase.docName)).toBe(kase.here);+ expect(ctx.moved.map((version) => version.bytes)).toEqual([between]);+ expect(getMetrics().storeRestatRefused).toBe(1);+ });++ test('gives up after three outside versions in a row, each in history, and writes nothing', async () => {+ const kase = ENGINELESS_CASES[0];+ let next = 0;+ const ctx = makeCtx({+ duringSave: () => {+ next += 1;+ writeDocFile(kase.docName, `graph TD\n A-->V${next}\n`);+ },+ });+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toEqual({+ kind: 'held',+ cause: 'keeps-changing',+ });++ expect(ctx.moved).toHaveLength(3);+ expect(readDocFile(kase.docName)).not.toBe(kase.here);+ expect(getMetrics().enginelessStore).toEqual({ 'held-exhausted': 1 });+ });++ test('an outside version that is not valid UTF-8 is never written over, at the save or the intake', async () => {+ const kase = ENGINELESS_CASES[2];+ const ctx = makeCtx();+ const { doc } = openWithUnsavedEdit(kase, ctx);+ const utf16 = Buffer.from('\ufeffexport const value = 5;\r\n', 'utf16le');+ writeFileSync(resolve(contentDir, kase.docName), utf16);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toMatchObject({+ kind: 'held',+ cause: 'not-utf8',+ path: resolve(contentDir, kase.docName),+ });+ expect(await applyExternalEnginelessChange(doc, kase.docName, ctx)).toBe('held');++ expect(readFileSync(resolve(contentDir, kase.docName)).equals(utf16)).toBe(true);+ expect(doc.getText('source').toString()).toBe(kase.here);+ expect(ctx.moved).toEqual([]);+ expect(backupsFor(kase.docName)).toEqual([]);+ expect(getMetrics().enginelessStore).toEqual({ 'held-not-utf8': 1 });+ expect(getMetrics().enginelessIntake).toEqual({ 'held-not-utf8': 1 });+ });+});++describe('applyExternalEnginelessChange', () => {+ test('applies the disk version live when nothing is unsaved', async () => {+ const kase = ENGINELESS_CASES[0];+ const ctx = makeCtx();+ writeDocFile(kase.docName, kase.saved);+ const doc = new Y.Doc();+ loadMermaidDoc(doc, kase.docName, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await applyExternalEnginelessChange(doc, kase.docName, ctx)).toBe('applied');++ expect(doc.getText('source').toString()).toBe(kase.outside);+ expect(ctx.lkgCache.get(kase.docName)).toBe(kase.outside);+ expect(ctx.receipts.get(kase.docName)).toMatchObject({+ hash: contentHash(kase.outside),+ via: 'agreed',+ });+ expect(ctx.moved).toEqual([]);+ });++ test('keeps unsaved edits live, moves the outside version to history once, and the next store writes the edits', async () => {+ const kase = ENGINELESS_CASES[1];+ const ctx = makeCtx();+ const { doc } = openWithUnsavedEdit(kase, ctx);+ writeDocFile(kase.docName, kase.outside);++ expect(await applyExternalEnginelessChange(doc, kase.docName, ctx)).toBe('kept-live');+ expect(doc.getText('source').toString()).toBe(kase.here);+ expect(readDocFile(kase.docName)).toBe(kase.outside);++ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('persisted');+ expect(readDocFile(kase.docName)).toBe(kase.here);+ expect(ctx.moved).toEqual([+ { docName: kase.docName, side: 'theirs', bytes: kase.outside, fileType: kase.fileType },+ ]);+ });++ test('takes nothing in when the file holds its own last write', async () => {+ const kase = ENGINELESS_CASES[2];+ const ctx = makeCtx();+ const doc = new Y.Doc();+ editTo(doc, kase.here);+ expect(await storeMermaidDoc(doc, kase.docName, 'person', ctx)).toBe('persisted');+ editTo(doc, `${kase.here}// more\n`);++ expect(await applyExternalEnginelessChange(doc, kase.docName, ctx)).toBe('unchanged');+ expect(doc.getText('source').toString()).toBe(`${kase.here}// more\n`);+ expect(ctx.moved).toEqual([]);});});@@ -127,6 +523,13 @@ describe('loadMermaidDoc', () => {expect(doc.getXmlFragment('default').length).toBe(0);});+ test('records an agreed receipt for the bytes it read', () => {+ writeMmd(SRC);+ const ctx = makeCtx();+ loadMermaidDoc(new Y.Doc(), DOC, ctx);+ expect(ctx.receipts.get(DOC)).toMatchObject({ hash: contentHash(SRC), via: 'agreed' });+ });+test('lazy: a missing file seeds nothing (admitting a doc never creates disk)', () => {const ctx = makeCtx();const doc = new Y.Doc();diff --git a/packages/server/src/mermaid-persistence.ts b/packages/server/src/mermaid-persistence.tsindex 8896d4e0c..de16615fc 100644--- a/packages/server/src/mermaid-persistence.ts+++ b/packages/server/src/mermaid-persistence.ts@@ -6,31 +6,74 @@import { existsSync, readFileSync } from 'node:fs';import { resolve } from 'node:path';import type { LocalTransactionOrigin } from '@hocuspocus/server';-import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';+import {+ isExcalidrawDocFile,+ isMermaidDocFile,+ LINEAGE_EPOCH_KEY,+} from '@inkeep/open-knowledge-core';import { atomicWriteFile } from '@inkeep/open-knowledge-core/server';import type * as Y from 'yjs';+import type { DiskReceipt, FileObservation } from './disk-receipts.ts';import { docNameToRelativePath } from './doc-extensions.ts';import { assertNoSymlinkEscape } from './fs-safety.ts';import { tracedMkdir } from './fs-traced.ts';+import { errnoCode } from './http/handler-utils.ts';import { getLogger } from './logger.ts';+import {+ type EnginelessFileType,+ type KeptCopy,+ keepNoEngineVersion,+ type MergeHistoryRecorder,+} from './merge-history.ts';+import {+ incrementEnginelessIntake,+ incrementEnginelessStore,+ incrementStoreDiskCompareReadRetries,+ incrementStoreRestatRefused,+} from './metrics.ts';import { isWithinDir } from './path-utils.ts';+import { heldFor, heldNotUtf8, type SaveHold } from './save-hold.ts';import { contentScopedAtomicFs } from './server-content-policy.ts';+import {+ assertNeverDiskCompare,+ COMPARE_READ_RETRY_DELAYS_MS,+ compareDiskBeforeReplace,+ type DiskCompareOutcome,+ restatFile,+ StoreRestatFailedError,+ StoreRestatRefusedError,+ statObservation,+} from './store-compare.ts';+import { contentHash } from './version-hash.ts';const log = getLogger('mermaid-persistence');+const MAX_OUTSIDE_VERSIONS_PER_STORE = 3;+export const MERMAID_SOURCE_ORIGIN = {source: 'local' as const,skipStoreHooks: true,context: { origin: 'mermaid-source' },} as const satisfies LocalTransactionOrigin;+interface EnginelessReceipts {+ get(docName: string): DiskReceipt | undefined;+ recordAgreed(docName: string, content: string, observation?: FileObservation): void;+ recordOwnWrite(docName: string, content: string, observation?: FileObservation): void;+}+export interface MermaidPersistenceCtx {contentDir: string;+ home: string;assertContentPath?: (path: string) => void;lkgCache: Map<string, string>;+ receipts: EnginelessReceipts;+ history: Pick<MergeHistoryRecorder, 'saveNoEngine' | 'noticeNoEngine'> | null;}-export type StoreMermaidOutcome = 'persisted' | 'no-op' | 'reconciled' | 'write-failed';+export type StoreMermaidOutcome = 'persisted' | 'no-op' | 'kept-live' | 'write-failed' | SaveHold;++type ApplyExternalEnginelessOutcome = 'applied' | 'kept-live' | 'unchanged' | 'held';function mermaidAbsPath(documentName: string, contentDir: string): string {if (documentName.includes('\x00')) {@@ -43,6 +86,12 @@ function mermaidAbsPath(documentName: string, contentDir: string): string {return filePath;}+function enginelessFileType(documentName: string): EnginelessFileType {+ if (isMermaidDocFile(documentName)) return 'mermaid';+ if (isExcalidrawDocFile(documentName)) return 'excalidraw';+ return 'text';+}+function replaceSource(document: Y.Doc, raw: string, bumpLineage: boolean): void {const ytext = document.getText('source');document.transact(() => {@@ -54,6 +103,29 @@ function replaceSource(document: Y.Doc, raw: string, bumpLineage: boolean): void}, MERMAID_SOURCE_ORIGIN);}+async function keepOutsideVersion(+ documentName: string,+ outside: string,+ ctx: MermaidPersistenceCtx,+): Promise<KeptCopy | null> {+ const fileType = enginelessFileType(documentName);+ const copy = await keepNoEngineVersion(+ ctx.history,+ ctx.home,+ ctx.contentDir,+ documentName,+ { side: 'theirs', bytes: outside },+ fileType,+ docNameToRelativePath(documentName),+ );+ if (copy !== null) ctx.history?.noticeNoEngine(documentName, 'theirs', fileType, copy);+ return copy;+}++function keptWhere(copy: KeptCopy): string {+ return copy.where === 'history' ? 'history' : `the backup folder (${copy.backup.display})`;+}+export function loadMermaidDoc(document: Y.Doc,documentName: string,@@ -76,6 +148,29 @@ export function loadMermaidDoc(}replaceSource(document, raw, true);ctx.lkgCache.set(documentName, raw);+ ctx.receipts.recordAgreed(documentName, raw, statObservation(filePath));+}++async function compareWithRetry(+ filePath: string,+ expectedHash: string | undefined,+ lkg: string | undefined,+ candidateHash: string,+): Promise<DiskCompareOutcome> {+ for (let attempt = 0; ; attempt++) {+ const compared = compareDiskBeforeReplace({+ path: filePath,+ receiptHash: expectedHash,+ baseHash: lkg === undefined ? undefined : contentHash(lkg),+ candidateHash,+ });+ const retryDelayMs = COMPARE_READ_RETRY_DELAYS_MS[attempt];+ if (compared.kind !== 'unreadable' || !compared.transient || retryDelayMs === undefined) {+ return compared;+ }+ incrementStoreDiskCompareReadRetries();+ await new Promise((done) => setTimeout(done, retryDelayMs));+ }}/** Serializes from `Y.Text('source')` (verbatim — precedent #38); atomic tmp+rename. */@@ -92,41 +187,175 @@ export async function storeMermaidDoc(if (content === lkg) return 'no-op';const filePath = mermaidAbsPath(documentName, ctx.contentDir);+ const candidateHash = contentHash(content);try {assertNoSymlinkEscape(filePath, ctx.contentDir);ctx.assertContentPath?.(filePath);await tracedMkdir(resolve(filePath, '..'), { recursive: true });- if (existsSync(filePath)) {- let disk: string | null = null;- try {- disk = readFileSync(filePath, 'utf-8');- } catch (readErr) {- if ((readErr as NodeJS.ErrnoException).code !== 'ENOENT') {+ let expectedHash = ctx.receipts.get(documentName)?.hash;+ let movedOutside = false;+ for (let round = 0; round < MAX_OUTSIDE_VERSIONS_PER_STORE; round++) {+ const compared = await compareWithRetry(filePath, expectedHash, lkg, candidateHash);+ let observation: FileObservation | null;+ switch (compared.kind) {+ case 'match':+ case 'drift':+ observation = compared.observation;+ break;+ case 'absent':+ observation = null;+ break;+ case 'unreadable':+ incrementEnginelessStore('held-unreadable');log.warn(- { documentName, err: readErr },- 'store: pre-write disk read failed (non-ENOENT); proceeding to write',+ { documentName, code: errnoCode(compared.error) },+ 'store: the file could not be read for the compare before the write; nothing was written and the next store tries again',);+ return heldFor('unreadable');+ case 'changed': {+ if (!compared.lossless) {+ incrementEnginelessStore('held-not-utf8');+ log.info(+ { documentName },+ 'store: the file changed outside to bytes that are not valid UTF-8; nothing was written so they stay on disk',+ );+ return heldNotUtf8(filePath, compared.observation);+ }+ const copy = await keepOutsideVersion(documentName, compared.text, ctx);+ if (copy === null) {+ incrementEnginelessStore('held-no-history-or-backup');+ log.warn(+ { documentName },+ 'store: the file changed outside and that version could not be kept in history or the backup folder; the version here stays live and the file is not written over',+ );+ return heldFor('no-history-or-backup');+ }+ movedOutside = true;+ expectedHash = contentHash(compared.text);+ log.info(+ { documentName, keptIn: copy.where },+ `store: the file changed outside; the version here stays and the outside version was kept in ${keptWhere(copy)}`,+ );+ continue;}- disk = null;+ default:+ return assertNeverDiskCompare(compared);}- if (disk !== null && disk !== lkg && disk !== content) {- replaceSource(document, disk, false);- ctx.lkgCache.set(documentName, disk);- return 'reconciled';+ try {+ await atomicWriteFile(filePath, content, {+ fs: contentScopedAtomicFs((path) => {+ assertNoSymlinkEscape(path, ctx.contentDir);+ ctx.assertContentPath?.(path);+ }),+ beforeRename: () => {+ const restat = restatFile(filePath, observation);+ if (restat.kind === 'failed')+ throw new StoreRestatFailedError(documentName, restat.error);+ if (restat.kind === 'moved') throw new StoreRestatRefusedError(documentName);+ },+ });+ } catch (writeErr) {+ if (writeErr instanceof StoreRestatRefusedError) {+ incrementStoreRestatRefused();+ log.info(+ { documentName },+ 'store: the file changed between the compare and the rename; the write was refused and the compare runs again',+ );+ continue;+ }+ if (writeErr instanceof StoreRestatFailedError) {+ incrementEnginelessStore('held-unreadable');+ log.warn(+ { documentName, code: writeErr.code },+ 'store: the file could not be re-read before the rename; nothing was written and the next store tries again',+ );+ return heldFor('unreadable');+ }+ throw writeErr;}+ if (compared.kind === 'absent') incrementEnginelessStore('absent');+ else if (!movedOutside) incrementEnginelessStore('match');+ ctx.lkgCache.set(documentName, content);+ ctx.receipts.recordOwnWrite(documentName, content, statObservation(filePath));+ if (!movedOutside) return 'persisted';+ incrementEnginelessStore('kept-live');+ return 'kept-live';}-- await atomicWriteFile(filePath, content, {- fs: contentScopedAtomicFs((path) => {- assertNoSymlinkEscape(path, ctx.contentDir);- ctx.assertContentPath?.(path);- }),- });- ctx.lkgCache.set(documentName, content);- return 'persisted';+ incrementEnginelessStore('held-exhausted');+ log.warn(+ { documentName, rounds: MAX_OUTSIDE_VERSIONS_PER_STORE },+ 'store: the file kept changing outside while it was being saved; nothing was written and the next store tries again',+ );+ return heldFor('keeps-changing');} catch (e) {log.warn({ documentName, err: e }, 'store: write failed');return 'write-failed';}}++export async function applyExternalEnginelessChange(+ document: Y.Doc,+ documentName: string,+ ctx: MermaidPersistenceCtx,+): Promise<ApplyExternalEnginelessOutcome> {+ const filePath = mermaidAbsPath(documentName, ctx.contentDir);+ let bytes: Buffer;+ try {+ assertNoSymlinkEscape(filePath, ctx.contentDir);+ ctx.assertContentPath?.(filePath);+ bytes = readFileSync(filePath);+ } catch (e) {+ if (errnoCode(e) !== 'ENOENT') {+ log.warn({ documentName, err: e }, 'intake: could not read the changed file');+ }+ return 'unchanged';+ }+ const disk = bytes.toString('utf8');+ if (!Buffer.from(disk, 'utf8').equals(bytes)) {+ incrementEnginelessIntake('held-not-utf8');+ log.warn(+ { documentName },+ 'intake: the file changed outside to bytes that are not valid UTF-8; nothing was taken in',+ );+ return 'held';+ }+ const lkg = ctx.lkgCache.get(documentName);+ if (disk === lkg || contentHash(disk) === ctx.receipts.get(documentName)?.hash) {+ incrementEnginelessIntake('unchanged');+ return 'unchanged';+ }+ const live = document.getText('source').toString();+ if (live === disk) {+ ctx.lkgCache.set(documentName, disk);+ ctx.receipts.recordAgreed(documentName, disk, statObservation(filePath));+ incrementEnginelessIntake('unchanged');+ return 'unchanged';+ }+ if (live === (lkg ?? '')) {+ replaceSource(document, disk, false);+ ctx.lkgCache.set(documentName, disk);+ ctx.receipts.recordAgreed(documentName, disk, statObservation(filePath));+ incrementEnginelessIntake('applied');+ return 'applied';+ }+ const copy = await keepOutsideVersion(documentName, disk, ctx);+ if (copy === null) {+ incrementEnginelessIntake('held-no-history-or-backup');+ log.warn(+ { documentName },+ 'intake: the file changed outside under unsaved edits and that version could not be kept in history or the backup folder; the version here stays live',+ );+ return 'held';+ }+ if (ctx.lkgCache.get(documentName) === lkg) {+ ctx.lkgCache.set(documentName, disk);+ ctx.receipts.recordAgreed(documentName, disk, statObservation(filePath));+ }+ incrementEnginelessIntake('kept-live');+ log.info(+ { documentName, keptIn: copy.where },+ `intake: the file changed outside under unsaved edits; the version here stays and the outside version was kept in ${keptWhere(copy)}`,+ );+ return 'kept-live';+}diff --git a/packages/server/src/metrics.test.ts b/packages/server/src/metrics.test.tsindex f395fd22d..4c0991085 100644--- a/packages/server/src/metrics.test.ts+++ b/packages/server/src/metrics.test.ts@@ -162,7 +162,11 @@ describe('reconciliation metrics', () => {key === 'observerAResidualMergeSpliceUnavailable' ||key === 'storeDiskCompare' ||key === 'receiptIntakeSkip' ||- key === 'receiptAtLoad'+ key === 'receiptAtLoad' ||+ key === 'managedArtifactMerge' ||+ key === 'enginelessStore' ||+ key === 'enginelessIntake' ||+ key === 'configOutsideChange') {expect(value).toEqual({});} else {diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.tsindex b6538183f..f48f5ca31 100644--- a/packages/server/src/metrics.ts+++ b/packages/server/src/metrics.ts@@ -40,6 +40,45 @@ export type ReceiptIntakeSkip = 'echo' | 'superseded';export type ReceiptAtLoad = 'unchanged' | 'changed' | 'missing';+export type EnginelessStoreOutcome =+ | 'match'+ | 'kept-live'+ | 'held-no-history-or-backup'+ | 'held-unreadable'+ | 'held-exhausted'+ | 'held-not-utf8'+ | 'absent';++export type EnginelessIntakeOutcome =+ | 'applied'+ | 'kept-live'+ | 'unchanged'+ | 'held-no-history-or-backup'+ | 'held-not-utf8';++export type ManagedArtifactMergeOutcome =+ | 'applied'+ | 'unchanged'+ | 'merged'+ | 'both-kept'+ | 'kept-live'+ | 'stash-fallback'+ | 'held';++type ManagedArtifactMergeKey = `${'store' | 'intake'}:${ManagedArtifactMergeOutcome}`;++export type ConfigOutsideChangeOutcome =+ | 'applied'+ | 'applied-displaced'+ | 'rejected'+ | 'invalid-kept-live'+ | 'held-no-history-or-backup'+ | 'held-not-utf8'+ | 'held-exhausted'+ | 'deferred';++type ConfigOutsideChangeKey = `${'store' | 'intake'}:${ConfigOutsideChangeOutcome}`;+export interface ReconciliationMetrics {reconcileCount: number;conflictCount: number;@@ -146,6 +185,17 @@ export interface ReconciliationMetrics {managedArtifactReconcile: number;managedArtifactReconcileCheckpointCreated: number;managedArtifactReconcileDeduped: number;+ managedArtifactMerge: Partial<Record<ManagedArtifactMergeKey, number>>;+ enginelessStore: Partial<Record<EnginelessStoreOutcome, number>>;+ enginelessIntake: Partial<Record<EnginelessIntakeOutcome, number>>;+ configOutsideChange: Partial<Record<ConfigOutsideChangeKey, number>>;+ noEngineHistoryCheckpointCreated: number;+ noEngineHistoryCheckpointFailures: number;+ heldSaves: number;+ heldSaveRetries: number;+ heldSaveRetryFailures: number;+ displacedVersionBackups: number;+ displacedVersionBackupFailures: number;reDeriveBackstopTripped: number;/*** Count of Observer A settlement checks that detected a drain settling split-brain beyond@@ -294,6 +344,17 @@ const counters: ReconciliationMetrics = {managedArtifactReconcile: 0,managedArtifactReconcileCheckpointCreated: 0,managedArtifactReconcileDeduped: 0,+ managedArtifactMerge: {},+ enginelessStore: {},+ enginelessIntake: {},+ configOutsideChange: {},+ noEngineHistoryCheckpointCreated: 0,+ noEngineHistoryCheckpointFailures: 0,+ heldSaves: 0,+ heldSaveRetries: 0,+ heldSaveRetryFailures: 0,+ displacedVersionBackups: 0,+ displacedVersionBackupFailures: 0,reDeriveBackstopTripped: 0,bridgeSplitBrainRederives: 0,bridgeSplitBrainRederivesSuppressed: 0,@@ -685,6 +746,58 @@ export function incrementManagedArtifactReconcileDeduped(): void {counters.managedArtifactReconcileDeduped++;}+export function incrementManagedArtifactMerge(+ site: 'store' | 'intake',+ outcome: ManagedArtifactMergeOutcome,+): void {+ const key: ManagedArtifactMergeKey = `${site}:${outcome}`;+ counters.managedArtifactMerge[key] = (counters.managedArtifactMerge[key] ?? 0) + 1;+}++export function incrementEnginelessStore(outcome: EnginelessStoreOutcome): void {+ counters.enginelessStore[outcome] = (counters.enginelessStore[outcome] ?? 0) + 1;+}++export function incrementEnginelessIntake(outcome: EnginelessIntakeOutcome): void {+ counters.enginelessIntake[outcome] = (counters.enginelessIntake[outcome] ?? 0) + 1;+}++export function incrementConfigOutsideChange(+ site: 'store' | 'intake',+ outcome: ConfigOutsideChangeOutcome,+): void {+ const key: ConfigOutsideChangeKey = `${site}:${outcome}`;+ counters.configOutsideChange[key] = (counters.configOutsideChange[key] ?? 0) + 1;+}++export function incrementHeldSave(): void {+ counters.heldSaves++;+}++export function incrementHeldSaveRetry(): void {+ counters.heldSaveRetries++;+}++export function incrementHeldSaveRetryFailures(): void {+ counters.heldSaveRetryFailures++;+}++export function incrementDisplacedVersionBackups(): void {+ counters.displacedVersionBackups++;+}++export function incrementDisplacedVersionBackupFailures(): void {+ counters.displacedVersionBackupFailures++;+}++export function incrementNoEngineHistoryCheckpointCreated(): void {+ counters.noEngineHistoryCheckpointCreated++;+}++export function incrementNoEngineHistoryCheckpointFailures(): void {+ counters.noEngineHistoryCheckpointFailures++;+}+export function incrementReDeriveBackstopTripped(): void {counters.reDeriveBackstopTripped++;}@@ -921,6 +1034,10 @@ export function getMetrics(): ReconciliationMetrics {storeDiskCompare: { ...counters.storeDiskCompare },receiptIntakeSkip: { ...counters.receiptIntakeSkip },receiptAtLoad: { ...counters.receiptAtLoad },+ managedArtifactMerge: { ...counters.managedArtifactMerge },+ enginelessStore: { ...counters.enginelessStore },+ enginelessIntake: { ...counters.enginelessIntake },+ configOutsideChange: { ...counters.configOutsideChange },mapDrivenSpliceFallback: { ...counters.mapDrivenSpliceFallback },mapDrivenSpliceMemoSkips: { ...counters.mapDrivenSpliceMemoSkips },observerAResidualMergeSpliceUnavailable: {@@ -1028,6 +1145,17 @@ export function resetMetrics(): void {counters.managedArtifactReconcile = 0;counters.managedArtifactReconcileCheckpointCreated = 0;counters.managedArtifactReconcileDeduped = 0;+ counters.managedArtifactMerge = {};+ counters.enginelessStore = {};+ counters.enginelessIntake = {};+ counters.configOutsideChange = {};+ counters.noEngineHistoryCheckpointCreated = 0;+ counters.noEngineHistoryCheckpointFailures = 0;+ counters.heldSaves = 0;+ counters.heldSaveRetries = 0;+ counters.heldSaveRetryFailures = 0;+ counters.displacedVersionBackups = 0;+ counters.displacedVersionBackupFailures = 0;counters.reDeriveBackstopTripped = 0;counters.bridgeSplitBrainRederives = 0;counters.bridgeSplitBrainRederivesSuppressed = 0;diff --git a/packages/server/src/path-identity.test.ts b/packages/server/src/path-identity.test.tsindex 8c8fa12ee..c05b00efa 100644--- a/packages/server/src/path-identity.test.ts+++ b/packages/server/src/path-identity.test.ts@@ -172,6 +172,7 @@ describe('directory identity across server components', () => {writeFileSync(join(contentDir, `${docName}.md`), seed);const state = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir,@@ -210,6 +211,7 @@ describe('directory identity across server components', () => {writeFileSync(outsidePath, seed);const state = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir,@@ -248,6 +250,7 @@ describe('directory identity across server components', () => {const shadow = await initShadowRepo(projectDir);const state = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir,@@ -580,6 +583,7 @@ describe('one directory identity for watcher keys and linked documents', () => {symlinkSync(target, join(canonicalContentDir, `${docName}.md`));}const loader = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir,@@ -588,6 +592,7 @@ describe('one directory identity for watcher keys and linked documents', () => {});const storeState = new DocumentDurabilityState();const storer = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir,diff --git a/packages/server/src/persistence-defer-hold.test.ts b/packages/server/src/persistence-defer-hold.test.tsindex 923d80fc7..809a39742 100644--- a/packages/server/src/persistence-defer-hold.test.ts+++ b/packages/server/src/persistence-defer-hold.test.ts@@ -76,6 +76,7 @@ async function createStoreHarness(});const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: projectRoot,projectDir: projectRoot,diff --git a/packages/server/src/persistence-deferred-store.test.ts b/packages/server/src/persistence-deferred-store.test.tsindex 6817399df..733ba32cf 100644--- a/packages/server/src/persistence-deferred-store.test.ts+++ b/packages/server/src/persistence-deferred-store.test.ts@@ -102,6 +102,7 @@ describe('batch-gated L1 persistence', () => {writeFileSync(docPath, 'initial\n', 'utf-8');const acks: Array<{ docName: string; sv: Uint8Array }> = [];const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -143,6 +144,7 @@ describe('batch-gated L1 persistence', () => {previousMarkdown: string | null;}> = [];const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -171,6 +173,7 @@ describe('batch-gated L1 persistence', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'clean\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -201,6 +204,7 @@ describe('batch-gated L1 persistence', () => {const goodPath = join(tmpDir, `${goodDocName}.md`);writeFileSync(goodPath, 'good base\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -238,6 +242,7 @@ describe('batch-gated L1 persistence', () => {writeFileSync(docPath, 'base\n', 'utf-8');let resetAttempts = 0;const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -273,6 +278,7 @@ describe('batch-gated L1 persistence', () => {writeFileSync(docPath, 'branch A base\n', 'utf-8');const acks: Array<{ docName: string; sv: Uint8Array }> = [];const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -311,6 +317,7 @@ describe('batch-gated L1 persistence', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'branch A base\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -354,6 +361,7 @@ describe('batch-gated L1 persistence', () => {let secondPendingAfterDiscardCall: Promise<unknown> | undefined;const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -420,6 +428,7 @@ describe('quiescence gate — deferCount cleanup on disk-write error', () => {writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -449,6 +458,7 @@ describe('quiescence gate — deferCount cleanup on disk-write error', () => {writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -531,6 +541,7 @@ describe('Y.Text-is-truth wiring (FR-33 / FR-35)', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, '', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -557,6 +568,7 @@ describe('Y.Text-is-truth wiring (FR-33 / FR-35)', () => {writeFileSync(docPath, '__cold__\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -612,6 +624,7 @@ describe('FR-9 — deferred-store-failed event + counter', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -654,6 +667,7 @@ describe('FR-9 — deferred-store-failed event + counter', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -687,6 +701,7 @@ describe('FR-9 — deferred-store-failed event + counter', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -746,6 +761,7 @@ describe('FR-9 — deferred-store-failed event + counter', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -795,6 +811,7 @@ describe('FR-9 — deferred-store-failed event + counter', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -910,6 +927,7 @@ describe('forceStore dispatch (staleness watchdog entry point)', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -933,6 +951,7 @@ describe('forceStore dispatch (staleness watchdog entry point)', () => {const docPath = join(tmpDir, `${docName}.md`);writeFileSync(docPath, 'initial\n', 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -957,6 +976,7 @@ describe('forceStore dispatch (staleness watchdog entry point)', () => {test('short-circuits synthetic docs without touching queues', async () => {const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,diff --git a/packages/server/src/persistence-flush-during-commit.test.ts b/packages/server/src/persistence-flush-during-commit.test.tsindex 25545b5d8..9abea6461 100644--- a/packages/server/src/persistence-flush-during-commit.test.ts+++ b/packages/server/src/persistence-flush-during-commit.test.ts@@ -81,6 +81,7 @@ test.each([async ({ commitDebounceMs, waitForTimer }) => {writeFileSync(join(contentDir, 'notes.md'), 'initial\n');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: tmpDir,diff --git a/packages/server/src/persistence-held-save.test.ts b/packages/server/src/persistence-held-save.test.tsnew file mode 100644index 000000000..5981a7694--- /dev/null+++ b/packages/server/src/persistence-held-save.test.ts@@ -0,0 +1,208 @@+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { CONFIG_DOC_NAME_PROJECT, type ConfigValidationError } from '@inkeep/open-knowledge-core';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import * as Y from 'yjs';+import * as fsTraced from './fs-traced.ts';+import type { MergeHistoryRecorder } from './merge-history.ts';+import { createPersistenceExtension } from './persistence.ts';+import type { VisibleHoldCause } from './save-hold.ts';++interface Rig {+ persistence: ReturnType<typeof createPersistenceExtension>;+ held: Array<{ docName: string; cause: VisibleHoldCause }>;+ cleared: string[];+ rejections: Array<{ docName: string; error: ConfigValidationError }>;+}++let root: string;+let contentDir: string;+let home: string;++function makeRig(): Rig {+ const held: Rig['held'] = [];+ const cleared: string[] = [];+ const rejections: Rig['rejections'] = [];+ const mergeHistory: MergeHistoryRecorder = {+ bothKept: () => {},+ keptLive: async () => false,+ saveNoEngine: async () => null,+ noticeNoEngine: () => {},+ noticeBackup: () => {},+ noticeHeld: (docName, cause) => {+ held.push({ docName, cause });+ },+ clearHeld: (docName) => {+ cleared.push(docName);+ },+ };+ const persistence = createPersistenceExtension({+ mergeHistory,+ ingestDiskAtStore: null,+ contentDir,+ projectDir: contentDir,+ configHomedirOverride: home,+ onConfigRejected: (docName, error) => {+ rejections.push({ docName, error });+ },+ });+ return { persistence, held, cleared, rejections };+}++async function open(rig: Rig, documentName: string): Promise<Y.Doc> {+ const document = new Y.Doc();+ await rig.persistence.extension.onLoadDocument?.({+ document,+ documentName,+ context: {},+ } as never);+ return document;+}++function edit(document: Y.Doc, text: string): void {+ document.transact(() => {+ const source = document.getText('source');+ source.delete(0, source.length);+ source.insert(0, text);+ }, 'person');+}++async function store(rig: Rig, document: Y.Doc, documentName: string): Promise<void> {+ await rig.persistence.extension.onStoreDocument?.({+ document,+ documentName,+ lastTransactionOrigin: 'person',+ lastContext: {},+ } as never);+}++function blockBackups(): void {+ mkdirSync(join(home, '.ok'), { recursive: true });+ writeFileSync(join(home, '.ok', 'edit-backups'), 'not a folder');+}++function unblockBackups(): void {+ rmSync(join(home, '.ok', 'edit-backups'), { force: true });+}++beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), 'ok-held-save-'));+ contentDir = join(root, 'project');+ home = join(root, 'home');+ mkdirSync(contentDir, { recursive: true });+ mkdirSync(home, { recursive: true });+});++afterEach(() => {+ vi.restoreAllMocks();+ rmSync(root, { recursive: true, force: true });+});++describe('a held save of a file with no merge engine', () => {+ test('raises its notice at every hold, stays due at every sweep, and withdraws the notice once the save lands', async () => {+ const rig = makeRig();+ writeFileSync(join(contentDir, 'flow.mmd'), 'graph TD\n A-->B\n');+ const document = await open(rig, 'flow.mmd');+ edit(document, 'graph TD\n A-->C\n');+ writeFileSync(join(contentDir, 'flow.mmd'), 'graph TD\n A-->D\n');+ blockBackups();++ await store(rig, document, 'flow.mmd');+ await rig.persistence.retryHeldSave(document, 'flow.mmd');++ expect(rig.held).toEqual([+ { docName: 'flow.mmd', cause: 'no-history-or-backup' },+ { docName: 'flow.mmd', cause: 'no-history-or-backup' },+ ]);+ expect(rig.persistence.isHeldSaveDue('flow.mmd')).toBe(true);+ expect(rig.persistence.hasHeldSave('flow.mmd')).toBe(true);+ expect(rig.cleared).toEqual([]);++ unblockBackups();+ await rig.persistence.retryHeldSave(document, 'flow.mmd');++ expect(rig.cleared).toEqual(['flow.mmd']);+ expect(rig.persistence.isHeldSaveDue('flow.mmd')).toBe(false);+ expect(rig.persistence.hasHeldSave('flow.mmd')).toBe(false);+ });++ test('a file that cannot be read raises a notice with that cause', async () => {+ const rig = makeRig();+ writeFileSync(join(contentDir, 'flow.mmd'), 'graph TD\n A-->B\n');+ const document = await open(rig, 'flow.mmd');+ edit(document, 'graph TD\n A-->C\n');+ vi.spyOn(fsTraced, 'tracedReadObservedSync').mockImplementation(() => {+ throw Object.assign(new Error('denied'), { code: 'EACCES' });+ });++ await store(rig, document, 'flow.mmd');++ expect(rig.held).toEqual([{ docName: 'flow.mmd', cause: 'unreadable' }]);+ expect(rig.persistence.isHeldSaveDue('flow.mmd')).toBe(true);+ });++ test('a file that is not UTF-8 is not due again until it changes', async () => {+ const rig = makeRig();+ const path = join(contentDir, 'util.ts');+ writeFileSync(path, 'export const value = 1;\n');+ const document = await open(rig, 'util.ts');+ edit(document, 'export const value = 2;\n');+ writeFileSync(path, Buffer.from('export const value = 3;\r\n', 'utf16le'));++ await store(rig, document, 'util.ts');++ expect(rig.held).toEqual([{ docName: 'util.ts', cause: 'not-utf8' }]);+ expect(rig.persistence.isHeldSaveDue('util.ts')).toBe(false);++ writeFileSync(path, 'export const value = 4;\n');++ expect(rig.persistence.isHeldSaveDue('util.ts')).toBe(true);+ });+});++describe('a held settings save', () => {+ test('goes through the rejection channel with its cause and the file it names, not a notice', async () => {+ const rig = makeRig();+ const path = join(contentDir, '.ok', 'config.yml');+ mkdirSync(join(contentDir, '.ok'), { recursive: true });+ writeFileSync(path, 'mcp:\n autoStart: true\n');+ const document = await open(rig, CONFIG_DOC_NAME_PROJECT);+ edit(document, 'mcp:\n autoStart: false\n');+ writeFileSync(path, 'mcp: [unclosed\n');+ blockBackups();++ await store(rig, document, CONFIG_DOC_NAME_PROJECT);+ await rig.persistence.retryHeldSave(document, CONFIG_DOC_NAME_PROJECT);++ expect(rig.rejections).toEqual([+ {+ docName: CONFIG_DOC_NAME_PROJECT,+ error: { code: 'SAVE_HELD', cause: 'no-history-or-backup', file: '.ok/config.yml' },+ },+ ]);+ expect(rig.held).toEqual([]);+ });++ test('is sent again when its cause changes, and only then', async () => {+ const rig = makeRig();+ const path = join(contentDir, '.ok', 'config.yml');+ mkdirSync(join(contentDir, '.ok'), { recursive: true });+ writeFileSync(path, 'mcp:\n autoStart: true\n');+ const document = await open(rig, CONFIG_DOC_NAME_PROJECT);+ edit(document, 'mcp:\n autoStart: false\n');+ writeFileSync(path, 'mcp: [unclosed\n');+ blockBackups();+ await store(rig, document, CONFIG_DOC_NAME_PROJECT);++ writeFileSync(path, Buffer.from('mcp:\n note: caf\u00e9\n', 'latin1'));+ await rig.persistence.retryHeldSave(document, CONFIG_DOC_NAME_PROJECT);+ writeFileSync(path, Buffer.from('mcp:\n note: na\u00efve\n', 'latin1'));+ await rig.persistence.retryHeldSave(document, CONFIG_DOC_NAME_PROJECT);++ expect(rig.rejections.map(({ error }) => error)).toEqual([+ { code: 'SAVE_HELD', cause: 'no-history-or-backup', file: '.ok/config.yml' },+ { code: 'SAVE_HELD', cause: 'not-utf8', file: '.ok/config.yml' },+ ]);+ });+});diff --git a/packages/server/src/persistence-large-file-cap.test.ts b/packages/server/src/persistence-large-file-cap.test.tsindex 36411d795..7f9d6af1f 100644--- a/packages/server/src/persistence-large-file-cap.test.ts+++ b/packages/server/src/persistence-large-file-cap.test.ts@@ -34,6 +34,7 @@ describe('persistence large-file cap', () => {writeFileSync(filePath, '');truncateSync(filePath, DOCUMENT_OPEN_BYTE_LIMIT + 1);const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,});@@ -50,6 +51,7 @@ describe('persistence large-file cap', () => {const filePath = join(tmpDir, 'exact.md');writeFileSync(filePath, 'a'.repeat(DOCUMENT_OPEN_BYTE_LIMIT));const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,});diff --git a/packages/server/src/persistence-publication-receipt.test-helper.ts b/packages/server/src/persistence-publication-receipt.test-helper.tsindex bce0da8a1..34d04664e 100644--- a/packages/server/src/persistence-publication-receipt.test-helper.ts+++ b/packages/server/src/persistence-publication-receipt.test-helper.ts@@ -69,6 +69,7 @@ export async function createReceiptFixture(initial = 'initial\n') {durability.switchReconciledBaseScope('main');writeFileSync(docPath, initial, { flag: 'wx' });const options: ReceiptOptions = {+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,diff --git a/packages/server/src/persistence-publication-receipt.test.ts b/packages/server/src/persistence-publication-receipt.test.tsindex b85fcf87c..467ba0c44 100644--- a/packages/server/src/persistence-publication-receipt.test.ts+++ b/packages/server/src/persistence-publication-receipt.test.ts@@ -23,6 +23,7 @@ describe('successful publication receipt ownership', () => {test('ordinary publication remains usable without a receipt consumer', async () => {const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fixture.contentDir,projectDir: fixture.contentDir,@@ -42,6 +43,7 @@ describe('successful publication receipt ownership', () => {throw new Error('Receipt consumer cannot accept the occurrence');};const options: ReceiptOptions = {+ mergeHistory: null,ingestDiskAtStore: null,contentDir: fixture.contentDir,projectDir: fixture.contentDir,diff --git a/packages/server/src/persistence-removed-doc-publish.test.ts b/packages/server/src/persistence-removed-doc-publish.test.tsindex 4d7dc652f..6e017c270 100644--- a/packages/server/src/persistence-removed-doc-publish.test.ts+++ b/packages/server/src/persistence-removed-doc-publish.test.ts@@ -52,6 +52,7 @@ describe('persistence publish guard — a removed document is never republished'function persistenceWith(isRecentlyRemoved?: (name: string) => boolean) {return createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,diff --git a/packages/server/src/persistence-rename-backfill.test.ts b/packages/server/src/persistence-rename-backfill.test.tsindex 8804f63e5..723b58d2e 100644--- a/packages/server/src/persistence-rename-backfill.test.ts+++ b/packages/server/src/persistence-rename-backfill.test.ts@@ -81,6 +81,7 @@ describe('rename-log commitSha backfill', () => {writeFileSync(join(contentDir, 'alpha.md'), '# alpha\n');writeFileSync(join(contentDir, 'gamma.md'), '# gamma\n');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: tmpDir,diff --git a/packages/server/src/persistence-staleness-watchdog.test.ts b/packages/server/src/persistence-staleness-watchdog.test.tsindex b6020e9d5..28604f80c 100644--- a/packages/server/src/persistence-staleness-watchdog.test.ts+++ b/packages/server/src/persistence-staleness-watchdog.test.ts@@ -282,6 +282,27 @@ describe('exclusions', () => {expect(getMetrics().persistenceStalenessDetected).toBe(0);});+ test('retries the held save of a file it does not otherwise watch, and only a held one', async () => {+ await rig.watchdog.dispose();+ const held = new Set(['diagram.mmd', '__config__/project']);+ const retried: string[] = [];+ rig = makeRig({+ isHeldSaveDue: (name) => held.has(name),+ retryHeldSave: async (_document, name) => {+ retried.push(name);+ },+ });+ for (const name of ['diagram.mmd', '__config__/project', 'notes.txt', '__system__']) {+ rig.docs.set(name, makeDoc('held text\n'));+ }++ await rig.watchdog.sweep();++ expect(retried.sort()).toEqual(['__config__/project', 'diagram.mmd']);+ expect(rig.forceCalls).toEqual([]);+ expect(getMetrics().heldSaveRetries).toBe(2);+ });+test('skips docs frozen by lifecycle status', async () => {for (const status of MAP_FROZEN_STATUSES) {const doc = seedWedgedDoc(rig, `lifecycle-${status}`);@@ -546,6 +567,55 @@ describe('in-flight suppression against the real durability state', () => {});});+describe('a stalled held-save retry does not wedge the sweep', () => {+ test('a retry that never settles times out as a failed attempt, later documents still sweep, and neither the next sweep nor dispose waits on it', async () => {+ const retried: string[] = [];+ const local = makeRig({+ forceStoreTimeoutMs: 50,+ isHeldSaveDue: (name) => name === 'stuck.mmd',+ retryHeldSave: (_document, name) => {+ retried.push(name);+ return new Promise<void>(() => {});+ },+ });+ local.docs.set('stuck.mmd', makeDoc('held text\n'));+ seedWedgedDoc(local, 'z-healthy-doc');++ await local.watchdog.sweep();++ expect(retried).toEqual(['stuck.mmd']);+ expect(local.bases.get('z-healthy-doc')).toBe('# edited in memory\n');+ expect(getMetrics().heldSaveRetryFailures).toBe(1);++ await local.watchdog.sweep();++ expect(retried).toEqual(['stuck.mmd']);+ await expect(local.watchdog.dispose()).resolves.toBeUndefined();+ });++ test('a retry that throws is counted as a failed attempt and tried again at the next sweep', async () => {+ let attempts = 0;+ const local = makeRig({+ isHeldSaveDue: () => true,+ retryHeldSave: async () => {+ attempts++;+ throw new Error('injected retry failure');+ },+ });+ try {+ local.docs.set('diagram.mmd', makeDoc('held text\n'));++ await local.watchdog.sweep();+ await local.watchdog.sweep();++ expect(attempts).toBe(2);+ expect(getMetrics().heldSaveRetryFailures).toBe(2);+ } finally {+ await local.watchdog.dispose();+ }+ });+});+describe('a stalled forced store does not wedge the sweep', () => {test('a store that never settles times out, is suppressed, and later documents still sweep', async () => {const local = makeRig({ forceStoreTimeoutMs: 50 });diff --git a/packages/server/src/persistence-staleness-watchdog.ts b/packages/server/src/persistence-staleness-watchdog.tsindex d454b47aa..0a3f5e5bb 100644--- a/packages/server/src/persistence-staleness-watchdog.ts+++ b/packages/server/src/persistence-staleness-watchdog.ts@@ -5,6 +5,8 @@ import { isPersistenceExcludedDoc } from './cc1-broadcast.ts';import type { FreezingLifecycleStatus, LifecycleView } from './conflict-kinds.ts';import { getLogger } from './logger.ts';import {+ incrementHeldSaveRetry,+ incrementHeldSaveRetryFailures,incrementPersistenceStalenessDetected,incrementPersistenceStalenessForcedStores,incrementPersistenceStalenessForceStoreTimeouts,@@ -38,6 +40,8 @@ export interface StalenessWatchdogOptions {hasInFlight: (documentName: string) => boolean;forceStoreTimeoutMs?: number;msSinceLastUserTx?: (doc: Y.Doc, nowMs: number) => number | null;+ isHeldSaveDue?: (documentName: string) => boolean;+ retryHeldSave?: (document: Y.Doc, documentName: string) => Promise<void>;}export interface StalenessWatchdogHandle {@@ -65,6 +69,8 @@ export function createPersistenceStalenessWatchdog(const msSinceLastUserTx = options.msSinceLastUserTx ?? getMsSinceLastUserTx;const attempts = new Map<string, AttemptRecord>();+ const heldRetriesInFlight = new Set<string>();+ const heldRetryFailures = new Map<string, number>();let disposed = false;let sweepInFlight: Promise<void> | null = null;@@ -102,11 +108,22 @@ export function createPersistenceStalenessWatchdog(let divergent = 0;let forced = 0;let stoodDown = 0;+ let heldRetried = 0;const seen = new Set<string>();for (const [documentName, document] of options.getLoadedDocuments()) {if (disposed) return;seen.add(documentName);- if (isPersistenceExcludedDoc(documentName)) continue;+ if (isPersistenceExcludedDoc(documentName)) {+ if (+ options.retryHeldSave &&+ !heldRetriesInFlight.has(documentName) &&+ options.isHeldSaveDue?.(documentName) === true+ ) {+ heldRetried++;+ await retryHeldSaveWithin(options.retryHeldSave, document, documentName);+ }+ continue;+ }if (frozenStatusOf(document, documentName) !== null) {continue;}@@ -304,22 +321,74 @@ export function createPersistenceStalenessWatchdog(for (const name of attempts.keys()) {if (!seen.has(name)) attempts.delete(name);}+ for (const name of heldRetryFailures.keys()) {+ if (!seen.has(name)) heldRetryFailures.delete(name);+ }const summary = {scanned,divergent,forced,stoodDown,+ heldRetried,skippedInFlight,elapsedMs: now() - startedMs,};- if (divergent > 0 || forced > 0 || stoodDown > 0) {+ if (divergent > 0 || forced > 0 || stoodDown > 0 || heldRetried > 0) {log.info(summary, '[persistence-staleness] sweep complete');} else {log.debug(summary, '[persistence-staleness] sweep complete');}}+ async function retryHeldSaveWithin(+ retryHeldSave: NonNullable<StalenessWatchdogOptions['retryHeldSave']>,+ document: Y.Doc,+ documentName: string,+ ): Promise<void> {+ incrementHeldSaveRetry();+ let pendingRetry: Promise<void>;+ try {+ pendingRetry = retryHeldSave(document, documentName);+ } catch (err) {+ pendingRetry = Promise.reject(err);+ }+ heldRetriesInFlight.add(documentName);+ void pendingRetry+ .finally(() => {+ heldRetriesInFlight.delete(documentName);+ })+ .catch(() => {});+ const outcome = await raceForceStore(pendingRetry).catch((err: unknown) => {+ log.warn(+ { err, docName: documentName, failedAttempts: countHeldRetryFailure(documentName) },+ '[persistence-staleness] retrying a held save failed; it is tried again at the next sweep',+ );+ return 'failed' as const;+ });+ if (outcome === 'settled') {+ heldRetryFailures.delete(documentName);+ return;+ }+ if (outcome === 'timeout') {+ log.warn(+ {+ docName: documentName,+ forceStoreTimeoutMs,+ failedAttempts: countHeldRetryFailure(documentName),+ },+ `[persistence-staleness] retrying the held save of ${documentName} did not settle within ${forceStoreTimeoutMs}ms; counted as a failed attempt, and it is tried again at a sweep after it settles`,+ );+ }+ }++ function countHeldRetryFailure(documentName: string): number {+ incrementHeldSaveRetryFailures();+ const failed = (heldRetryFailures.get(documentName) ?? 0) + 1;+ heldRetryFailures.set(documentName, failed);+ return failed;+ }+async function raceForceStore(pendingStore: Promise<void>): Promise<'settled' | 'timeout'> {let timer: ReturnType<typeof setTimeout> | undefined;const deadline = new Promise<'timeout'>((resolve) => {diff --git a/packages/server/src/persistence-store-publish-order.test.ts b/packages/server/src/persistence-store-publish-order.test.tsindex 3bf72ff65..8c8039b1d 100644--- a/packages/server/src/persistence-store-publish-order.test.ts+++ b/packages/server/src/persistence-store-publish-order.test.ts@@ -48,6 +48,7 @@ describe('persistence publish ordering — a store must not publish bytes olderfunction createPersistence(): ReturnType<typeof createPersistenceExtension> {return createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,diff --git a/packages/server/src/persistence-store-superseded-drop.test.ts b/packages/server/src/persistence-store-superseded-drop.test.tsindex cb1e9fd03..e7c055c38 100644--- a/packages/server/src/persistence-store-superseded-drop.test.ts+++ b/packages/server/src/persistence-store-superseded-drop.test.ts@@ -63,6 +63,7 @@ describe('persistence superseded-store drop — a store that loses the publish rfunction createPersistence(): ReturnType<typeof createPersistenceExtension> {return createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,diff --git a/packages/server/src/persistence-tripwire-paste.test.ts b/packages/server/src/persistence-tripwire-paste.test.tsindex 4061f98c3..a576c8610 100644--- a/packages/server/src/persistence-tripwire-paste.test.ts+++ b/packages/server/src/persistence-tripwire-paste.test.ts@@ -512,6 +512,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -559,6 +560,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -598,6 +600,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -636,6 +639,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -673,6 +677,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -734,6 +739,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -787,6 +793,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,@@ -828,6 +835,7 @@ describe('persistence tripwire with an absent reconciled base', () => {const durabilityState = new DocumentDurabilityState();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: rig.tmpDir,projectDir: rig.tmpDir,diff --git a/packages/server/src/persistence-tripwire-read-failure.test.ts b/packages/server/src/persistence-tripwire-read-failure.test.tsindex b7e075580..3f2fc3231 100644--- a/packages/server/src/persistence-tripwire-read-failure.test.ts+++ b/packages/server/src/persistence-tripwire-read-failure.test.ts@@ -53,6 +53,7 @@ describe('tripwire reset readFileSync failure', () => {mkdirSync(join(contentDir, `${docName}.md`));const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,diff --git a/packages/server/src/persistence-tripwire-symlink.test.ts b/packages/server/src/persistence-tripwire-symlink.test.tsindex cdc3a6444..63776a408 100644--- a/packages/server/src/persistence-tripwire-symlink.test.ts+++ b/packages/server/src/persistence-tripwire-symlink.test.ts@@ -69,6 +69,7 @@ describe('tripwire reset symlink-escape', () => {symlinkSync(secretPath, docPath);const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,@@ -110,6 +111,7 @@ describe('tripwire reset symlink-escape', () => {symlinkSync('.ok/local/principal.json', join(contentDir, `${docName}.md`));const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,diff --git a/packages/server/src/persistence.test.ts b/packages/server/src/persistence.test.tsindex 5e136c1ab..946ea6657 100644--- a/packages/server/src/persistence.test.ts+++ b/packages/server/src/persistence.test.ts@@ -256,6 +256,7 @@ describe('persistence refuses links into private repository state', () => {function createPersistence(durabilityState = new DocumentDurabilityState()) {return createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,@@ -271,6 +272,7 @@ describe('persistence refuses links into private repository state', () => {const durabilityState = new DocumentDurabilityState();durabilityState.setReconciledBase('note', '# Before\n');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,@@ -516,6 +518,7 @@ describe('durable derived-index projection', () => {recordDurableStore,};const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,@@ -539,6 +542,7 @@ describe('durable derived-index projection', () => {const durabilityState = new DocumentDurabilityState();const recordDurableStore = vi.fn();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,@@ -569,6 +573,7 @@ describe('durable derived-index projection', () => {});await derivedDocumentIndex.close();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir,projectDir: contentDir,diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.tsindex 24a77c0cf..ffe1a6fa3 100644--- a/packages/server/src/persistence.ts+++ b/packages/server/src/persistence.ts@@ -1,5 +1,6 @@import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';import { realpath } from 'node:fs/promises';+import { homedir } from 'node:os';import { basename, dirname, join, relative, resolve } from 'node:path';import type { Extension } from '@hocuspocus/server';import type { MarkdownManager } from '@inkeep/open-knowledge-core';@@ -41,7 +42,13 @@ import {isPersistenceExcludedDoc,isSystemDoc,} from './cc1-broadcast.ts';-import { type ConfigPersistenceCtx, loadConfigDoc, storeConfigDoc } from './config-persistence.ts';+import {+ type ConfigPersistenceCtx,+ configDocAbsPath,+ loadConfigDoc,+ type StoreConfigDocOutcome,+ storeConfigDoc,+} from './config-persistence.ts';import type { ConflictAuthority } from './conflict-authority.ts';import {type FreezingLifecycleStatus,@@ -66,6 +73,7 @@ import {import { resolveDirectoryRoot, resolveNativePath } from './directory-root.ts';import { applyDiskContentToDoc, FILE_WATCHER_ORIGIN } from './disk-content-intake.ts';import type { FileObservation } from './disk-receipts.ts';+import { displayPathFor } from './display-path.ts';import {assertNeverStorePublishOutcome,type DeferredStoreDiscardCause,@@ -106,18 +114,23 @@ import {type ManagedArtifactCtx,managedArtifactContributorAttribution,managedArtifactTimelinePaths,+ type StoreManagedArtifactOutcome,storeManagedArtifactDoc,+ storeManagedArtifactWroteFile,} from './managed-artifact-persistence.ts';import { mdManager, schema } from './md-manager.ts';+import type { MergeHistoryRecorder } from './merge-history.ts';import {loadMermaidDoc,type MermaidPersistenceCtx,+ type StoreMermaidOutcome,storeMermaidDoc,} from './mermaid-persistence.ts';import {incrementDeferredStoreFailures,incrementGitAutoSaveFailure,incrementGitWriterCommitFailure,+ incrementHeldSave,incrementManagedArtifactReconcileCheckpointCreated,incrementManagedArtifactReconcileDeduped,incrementPersistenceDeferHold,@@ -150,6 +163,7 @@ import {getOrLoadRenameLogIndex,pendingRenameLogEntries,} from './rename-log.ts';+import { type SaveHold, visibleHoldCause } from './save-hold.ts';import { getConvergedFragmentWitness, OBSERVER_SYNC_ORIGIN } from './server-observers.ts';import type { ShadowRef, WriterIdentity } from './shadow-repo.ts';import {@@ -175,6 +189,66 @@ import {import { getMeter, setActiveSpanAttributes, withSpan } from './telemetry.ts';const log = getLogger('persistence');++type StoreSettlement = SaveHold | 'resolved' | 'neutral';++function assertNeverStoreOutcome(outcome: never): never {+ throw new Error(`unhandled store outcome: ${String(outcome)}`);+}++function configSettlement(outcome: StoreConfigDocOutcome, retry: boolean): StoreSettlement {+ if (typeof outcome === 'object') return outcome;+ switch (outcome) {+ case 'persisted':+ case 'reconciled':+ case 'reverted':+ return 'resolved';+ case 'no-op':+ return retry ? 'resolved' : 'neutral';+ case 'write-failed':+ return 'neutral';+ default:+ return assertNeverStoreOutcome(outcome);+ }+}++function managedArtifactSettlement(+ outcome: StoreManagedArtifactOutcome,+ retry: boolean,+): StoreSettlement {+ if (typeof outcome === 'object') return outcome;+ switch (outcome) {+ case 'persisted':+ case 'merged':+ case 'both-kept':+ case 'kept-live':+ case 'stash-fallback':+ case 'applied':+ return 'resolved';+ case 'no-op':+ return retry ? 'resolved' : 'neutral';+ case 'unchanged':+ case 'write-failed':+ return 'neutral';+ default:+ return assertNeverStoreOutcome(outcome);+ }+}++function enginelessSettlement(outcome: StoreMermaidOutcome, retry: boolean): StoreSettlement {+ if (typeof outcome === 'object') return outcome;+ switch (outcome) {+ case 'persisted':+ case 'kept-live':+ return 'resolved';+ case 'no-op':+ return retry ? 'resolved' : 'neutral';+ case 'write-failed':+ return 'neutral';+ default:+ return assertNeverStoreOutcome(outcome);+ }+}const compareLog = getLogger('store-compare');const MAX_STORE_COMPARE_RUNS = 3;@@ -416,6 +490,7 @@ export interface PersistenceOptions {lifecycleOf?: (document: Y.Doc, docName: string) => LifecycleView | null;ephemeral?: boolean;ingestDiskAtStore: StoreDiskIntake | null;+ mergeHistory: MergeHistoryRecorder | null;}export function captureDocSnapshotForPersistence(document: Y.Doc): {@@ -513,6 +588,10 @@ export interface PersistenceHandle {forgetObservedFile: (docName: string) => void;readonly configPersistenceCtx: ConfigPersistenceCtx;readonly managedArtifactCtx: ManagedArtifactCtx;+ readonly mermaidPersistenceCtx: MermaidPersistenceCtx;+ retryHeldSave: (document: Y.Doc, documentName: string) => Promise<void>;+ isHeldSaveDue: (documentName: string) => boolean;+ hasHeldSave: (documentName: string) => boolean;}export function createPersistenceExtension(options: PersistenceOptions): PersistenceHandle {@@ -556,6 +635,8 @@ export function createPersistenceExtension(options: PersistenceOptions): PersisthomedirOverride: options?.configHomedirOverride,onConfigRejected: options?.onConfigRejected,ephemeral,+ agreedDisk: new Map<string, string>(),+ history: options.mergeHistory,};const managedArtifactLkgCache = new Map<string, string>();@@ -567,13 +648,23 @@ export function createPersistenceExtension(options: PersistenceOptions): PersistgetReconciledBase: (docName) => durabilityState.getReconciledBase(docName),beforeReconcileDivergence: (document, docName, liveContent, diskContent) =>checkpointBeforeManagedArtifactReconcile(document, docName, liveContent, diskContent),+ history: options.mergeHistory,};const mermaidLkgCache = new Map<string, string>();const mermaidPersistenceCtx: MermaidPersistenceCtx = {assertContentPath: options?.assertContentPath,contentDir,+ home: options?.configHomedirOverride ?? homedir(),lkgCache: mermaidLkgCache,+ receipts: {+ get: (docName) => durabilityState.getReceipt(docName),+ recordAgreed: (docName, content, observation) =>+ durabilityState.recordReceiptAgreed(docName, content, observation),+ recordOwnWrite: (docName, content, observation) =>+ durabilityState.recordReceiptOwnWrite(docName, content, observation),+ },+ history: options.mergeHistory,};const tripwireResetFailedDocs = new Set<string>();@@ -2472,62 +2563,12 @@ export function createPersistenceExtension(options: PersistenceOptions): PersistlastContext: _lastContext,}) {if (isSystemDoc(documentName)) return;- if (isConfigDoc(documentName)) {- const outcome = await storeConfigDoc(- document,- documentName,- lastTransactionOrigin,- configPersistenceCtx,- );- if (outcome === 'persisted' || outcome === 'reconciled') {- try {- onConfigPersisted?.(documentName);- } catch (err) {- log.warn({ err, documentName }, '[persistence] onConfigPersisted callback failed');- }- }- return;- }- if (isManagedArtifactDoc(documentName)) {- const outcome = await storeManagedArtifactDoc(- document,- documentName,- lastTransactionOrigin,- managedArtifactCtx,- );- if (outcome === 'persisted') {- const writer = resolveWriterFromOrigin(lastTransactionOrigin, getPrincipal);- if (writer && writer.id !== SERVICE_WRITER.id && !writer.id.startsWith('agent-')) {- const attribution = managedArtifactContributorAttribution(documentName);- if (attribution) {- recordContributor(- attribution.docKey,- writer.id,- writer.name,- writer.id,- attribution.subject,- );- scheduleGitCommit();- }- }- try {- onManagedSkillPersisted?.(documentName);- } catch (err) {- log.warn(- { err, documentName },- '[persistence] onManagedSkillPersisted callback failed',- );- }- }- return;- }if (- isMermaidDoc(documentName) ||- isExcalidrawDoc(documentName) ||- isEditableTextDoc(documentName)+ isConfigDoc(documentName) ||+ isManagedArtifactDoc(documentName) ||+ isEnginelessDoc(documentName)) {- options?.assertContentPath?.(safeContentPath(documentName, contentDir));- await storeMermaidDoc(document, documentName, lastTransactionOrigin, mermaidPersistenceCtx);+ await storeOutsideContentPipeline(document, documentName, lastTransactionOrigin);return;}if (durabilityState.isBatchInProgress() || isStoreHeld(documentName)) {@@ -2568,6 +2609,134 @@ export function createPersistenceExtension(options: PersistenceOptions): Persist};}+ function isEnginelessDoc(documentName: string): boolean {+ return (+ isMermaidDoc(documentName) || isExcalidrawDoc(documentName) || isEditableTextDoc(documentName)+ );+ }++ const heldSaves = new Map<string, SaveHold>();++ function surfaceHeldSave(documentName: string, hold: SaveHold, causeChanged: boolean): void {+ const cause = visibleHoldCause(hold);+ if (cause === null) return;+ if (!isConfigDoc(documentName)) {+ options.mergeHistory?.noticeHeld(documentName, cause);+ return;+ }+ if (!causeChanged) return;+ const file = displayPathFor(+ configDocAbsPath(documentName, configPersistenceCtx),+ projectDir,+ configPersistenceCtx.homedirOverride ?? homedir(),+ );+ options.onConfigRejected?.(documentName, { code: 'SAVE_HELD', cause, file });+ }++ function settleHeldSave(documentName: string, settlement: StoreSettlement): void {+ if (settlement === 'neutral') return;+ if (settlement === 'resolved') {+ durabilityState.clearStoreRefused(documentName);+ heldSaves.delete(documentName);+ if (!isConfigDoc(documentName)) options.mergeHistory?.clearHeld(documentName);+ return;+ }+ incrementHeldSave();+ durabilityState.markStoreRefused(documentName);+ const previous = heldSaves.get(documentName);+ heldSaves.set(documentName, settlement);+ const causeChanged = previous?.cause !== settlement.cause;+ if (causeChanged && settlement.cause === 'not-utf8') {+ log.warn(+ { documentName },+ '[persistence] the file changed outside to bytes that are not valid UTF-8, so the save is held; it is tried again when the file changes',+ );+ }+ surfaceHeldSave(documentName, settlement, causeChanged);+ }++ function isHeldSaveDue(documentName: string): boolean {+ if (!durabilityState.isStoreRefused(documentName)) return false;+ const hold = heldSaves.get(documentName);+ if (hold?.cause !== 'not-utf8') return true;+ return restatFile(hold.path, hold.observation).kind !== 'same';+ }++ async function storeOutsideContentPipeline(+ document: Y.Doc,+ documentName: string,+ lastTransactionOrigin: unknown,+ ): Promise<void> {+ const retry = lastTransactionOrigin === null;+ if (isConfigDoc(documentName)) {+ const outcome = await storeConfigDoc(+ document,+ documentName,+ lastTransactionOrigin,+ configPersistenceCtx,+ );+ settleHeldSave(documentName, configSettlement(outcome, retry));+ if (outcome === 'persisted' || outcome === 'reconciled') {+ try {+ onConfigPersisted?.(documentName);+ } catch (err) {+ log.warn({ err, documentName }, '[persistence] onConfigPersisted callback failed');+ }+ }+ return;+ }+ if (isManagedArtifactDoc(documentName)) {+ const outcome = await storeManagedArtifactDoc(+ document,+ documentName,+ lastTransactionOrigin,+ managedArtifactCtx,+ );+ settleHeldSave(documentName, managedArtifactSettlement(outcome, retry));+ if (storeManagedArtifactWroteFile(outcome)) {+ const writer = resolveWriterFromOrigin(lastTransactionOrigin, getPrincipal);+ if (writer && writer.id !== SERVICE_WRITER.id && !writer.id.startsWith('agent-')) {+ const attribution = managedArtifactContributorAttribution(documentName);+ if (attribution) {+ recordContributor(+ attribution.docKey,+ writer.id,+ writer.name,+ writer.id,+ attribution.subject,+ );+ scheduleGitCommit();+ }+ }+ try {+ onManagedSkillPersisted?.(documentName);+ } catch (err) {+ log.warn({ err, documentName }, '[persistence] onManagedSkillPersisted callback failed');+ }+ }+ return;+ }+ options?.assertContentPath?.(safeContentPath(documentName, contentDir));+ const outcome = await storeMermaidDoc(+ document,+ documentName,+ lastTransactionOrigin,+ mermaidPersistenceCtx,+ );+ settleHeldSave(documentName, enginelessSettlement(outcome, retry));+ }++ async function retryHeldSave(document: Y.Doc, documentName: string): Promise<void> {+ if (+ !isConfigDoc(documentName) &&+ !isManagedArtifactDoc(documentName) &&+ !isEnginelessDoc(documentName)+ ) {+ return;+ }+ await storeOutsideContentPipeline(document, documentName, null);+ }+async function forceStore(document: Y.Doc, documentName: string): Promise<void> {if (isPersistenceExcludedDoc(documentName)) {return;@@ -2596,5 +2765,9 @@ export function createPersistenceExtension(options: PersistenceOptions): PersistforgetObservedFile,configPersistenceCtx,managedArtifactCtx,+ mermaidPersistenceCtx,+ retryHeldSave,+ isHeldSaveDue,+ hasHeldSave: (documentName) => heldSaves.has(documentName),};}diff --git a/packages/server/src/reconcile-own-flush-window.test.ts b/packages/server/src/reconcile-own-flush-window.test.tsindex 6b61d52da..4f0ac6a55 100644--- a/packages/server/src/reconcile-own-flush-window.test.ts+++ b/packages/server/src/reconcile-own-flush-window.test.ts@@ -102,6 +102,7 @@ async function drivePhantomDivergence(let windowFired = false;let windowGuard: Promise<ReconcileBeforeWriteResult> | undefined;const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -206,6 +207,7 @@ describe('reconcileDiskBeforeAgentWrite — own persistence flush is not foreignwriteFileSync(docPath, BASE_CONTENT, 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -245,6 +247,7 @@ describe('reconcileDiskBeforeAgentWrite — own persistence flush is not foreignlet laterFlush: Promise<void> | undefined;let peekAfterLaterStart: string | undefined;const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -314,6 +317,7 @@ describe('reconcileDiskBeforeAgentWrite — overlapping own flushes are not forelet conflictAfterGuard: boolean | undefined;const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: async (name, _path, content) => {const taken = await reconcileDiskBeforeAgentWrite(durabilityState,diff --git a/packages/server/src/save-hold.ts b/packages/server/src/save-hold.tsnew file mode 100644index 000000000..5a5a33bae--- /dev/null+++ b/packages/server/src/save-hold.ts@@ -0,0 +1,42 @@+import type { DocNoticeWire } from '@inkeep/open-knowledge-core';+import type { FileObservation } from './disk-receipts.ts';++export type VisibleHoldCause = Extract<DocNoticeWire, { kind: 'save-held' }>['cause'];++export type SaveHold =+ | {+ readonly kind: 'held';+ readonly cause: 'unreadable' | 'edits-changing' | 'no-history-or-backup' | 'keeps-changing';+ }+ | {+ readonly kind: 'held';+ readonly cause: 'not-utf8';+ readonly path: string;+ readonly observation: FileObservation;+ };++export function heldFor(cause: Exclude<SaveHold['cause'], 'not-utf8'>): SaveHold {+ return { kind: 'held', cause };+}++export function heldNotUtf8(path: string, observation: FileObservation): SaveHold {+ return { kind: 'held', cause: 'not-utf8', path, observation };+}++export function visibleHoldCause(hold: SaveHold): VisibleHoldCause | null {+ switch (hold.cause) {+ case 'no-history-or-backup':+ case 'keeps-changing':+ case 'not-utf8':+ case 'unreadable':+ return hold.cause;+ case 'edits-changing':+ return null;+ default:+ return assertNeverHold(hold);+ }+}++function assertNeverHold(hold: never): never {+ throw new Error(`unhandled save hold: ${JSON.stringify(hold)}`);+}diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex f50626826..a260ab35e 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -84,7 +84,11 @@ import {import {CC1Broadcaster,isConfigDoc,+ isEditableTextDoc,+ isExcalidrawDoc,isManagedArtifactDoc,+ isMermaidDoc,+ isPersistenceExcludedDoc,isReservedForUserTree,SYSTEM_DOC_NAME,} from './cc1-broadcast.ts';@@ -97,6 +101,7 @@ import {} from './config-file-watcher.ts';import {applyExternalConfigChange,+ configDocAbsPath,isConfigEcho,resetConfigDocForTest,} from './config-persistence.ts';@@ -132,17 +137,17 @@ import {} from './derived-document-index.ts';import { resolveDirectoryRoot } from './directory-root.ts';import { applyDiskContentToDoc } from './disk-content-intake.ts';-import { DiskReceiptLog } from './disk-receipts.ts';+import { DiskReceiptLog, receiptFileIsGoneIn } from './disk-receipts.ts';+import { displayPathFor } from './display-path.ts';import {canonicalDocName,docNameToRelativePath,getDocExtension,isRegisteredMarkdownDocName,- SUPPORTED_DOC_EXTENSIONS,stripDocExtension,} from './doc-extensions.ts';import { runDocLineageGuard } from './doc-lineage-guard.ts';-import { DocNoticeLedger } from './doc-notices.ts';+import { DocNoticeLedger, type NoticeFile } from './doc-notices.ts';import {DocumentDurabilityState,type StaleExternalWriteConflict,@@ -246,6 +251,7 @@ import {import {applyExternalManagedArtifactChange,homeFor,+ managedArtifactAbsPath,managedArtifactDocNameForPath,managedArtifactSkillsRoots,} from './managed-artifact-persistence.ts';@@ -254,6 +260,7 @@ import { recoverPendingManagedRename } from './managed-rename-journal.ts';import type { NativeTomlMcpEditor } from './mcp-config-reconciler.ts';import { mdManager, schema } from './md-manager.ts';import { createMergeHistoryRecorder, type MergeHistoryWriter } from './merge-history.ts';+import { applyExternalEnginelessChange } from './mermaid-persistence.ts';import {incrementBatch,incrementBranchSwitch,@@ -634,20 +641,7 @@ export function createServer(options: ServerOptions): ServerInstance {const diskReceipts = new DiskReceiptLog({path: join(getLocalDir(projectDir), 'receipts.jsonl'),});- const receiptFileIsGone = (docName: string): boolean => {- for (const extension of SUPPORTED_DOC_EXTENSIONS) {- const candidate = resolve(contentDir, `${docName}${extension}`);- if (!isWithinDir(candidate, contentDir)) return false;- try {- lstatSync(candidate);- return false;- } catch (err) {- const code = errnoCode(err);- if (code !== 'ENOENT' && code !== 'ENOTDIR') return false;- }- }- return true;- };+ const receiptFileIsGone = receiptFileIsGoneIn(contentDir);const durabilityState = new DocumentDurabilityState(initialBranch, {persistencePath: join(getLocalDir(projectDir), 'stale-external-writes.json'),receipts: diskReceipts,@@ -1320,6 +1314,25 @@ export function createServer(options: ServerOptions): ServerInstance {},() => {},);+ const noticeDisplayPath = (abs: string): string =>+ displayPathFor(abs, projectDir, configHomedirOverride ?? homedir());+ let heldSaveProbe: (docName: string) => boolean = () => true;+ const noticeFileOutsideContent = (docName: string): NoticeFile | null => {+ let abs: string;+ try {+ if (isConfigDoc(docName)) abs = configDocAbsPath(docName, persistence.configPersistenceCtx);+ else if (isManagedArtifactDoc(docName)) {+ abs = managedArtifactAbsPath(docName, persistence.managedArtifactCtx);+ } else return null;+ } catch (err) {+ log.debug(+ { err, docName },+ '[doc-notices] no file to name for a notice outside the content folder',+ );+ return null;+ }+ return { abs, display: noticeDisplayPath(abs) };+ };const docNotices = new DocNoticeLedger({projectDir,contentDir,@@ -1327,6 +1340,15 @@ export function createServer(options: ServerOptions): ServerInstance {isReady: () => readyForNotices,signal: () => cc1Broadcaster?.signal('sync-status'),isHeld: (docName) => vanishedDocuments.has(docName),+ isSaveHeld: (docName) => heldSaveProbe(docName),+ resolveFile: noticeFileOutsideContent,+ });+ const mergeHistory = createMergeHistoryRecorder({+ getShadow: () => shadowRef?.current,+ contentRoot: contentRoot ?? '',+ getBranch: getStorageBranch,+ writeCheckpoint: options.mergeHistoryWriter,+ notices: docNotices,});const offlineRemovalsReconciled = Promise.withResolvers<void>();@@ -1746,7 +1768,7 @@ export function createServer(options: ServerOptions): ServerInstance {try {const content = readFileSync(configResult.path, 'utf-8');- applyExternalConfigChange(+ await applyExternalConfigChange(hocuspocus.documents.get(CONFIG_DOC_NAME_PROJECT) ?? null,CONFIG_DOC_NAME_PROJECT,content,@@ -2282,6 +2304,7 @@ export function createServer(options: ServerOptions): ServerInstance {isRecentlyRemoved: (docName) => recentlyRemovedDocs.has(docName),mdManager: options.mdManager,getLossRing: () => lossRing,+ mergeHistory,ingestDiskAtStore: async (docName, absPath, content) => {let outcome: DiskIntakeOutcome;try {@@ -2304,6 +2327,7 @@ export function createServer(options: ServerOptions): ServerInstance {};persistence = createPersistenceExtension({ ...persistenceOpts, durabilityState });+ heldSaveProbe = (docName) => persistence.hasHeldSave(docName);hocuspocus = new Hocuspocus({quiet,@@ -2386,6 +2410,9 @@ export function createServer(options: ServerOptions): ServerInstance {getLoadedDocuments: () => hp.documents,lifecycleOf: (document, documentName) => conflicts.lifecycleOf(document, documentName),forceStore: (document, documentName) => persistence.forceStore(document, documentName),+ isHeldSaveDue: (documentName) => persistence.isHeldSaveDue(documentName),+ retryHeldSave: (document, documentName) =>+ persistence.retryHeldSave(document, documentName),getBase: (documentName) => durabilityState.getReconciledBase(documentName),isBatchActive: () => durabilityState.isBatchInProgress(),hasInFlight: (documentName) => durabilityState.inFlightFlushCount(documentName) > 0,@@ -3000,14 +3027,6 @@ export function createServer(options: ServerOptions): ServerInstance {}}- const mergeHistory = createMergeHistoryRecorder({- getShadow: () => shadowRef.current,- contentRoot: contentRoot ?? '',- getBranch: getStorageBranch,- writeCheckpoint: options.mergeHistoryWriter,- notices: docNotices,- });-const CHECKPOINT_KIND_BY_MINT_SITE = {delete: 'external-change-rescue',rename: 'external-change-rescue',@@ -4342,6 +4361,7 @@ export function createServer(options: ServerOptions): ServerInstance {await derivedDocumentIndex.recordFileTargetUpsert(event.relativePath);invalidateReferencedAssetsCache?.();signalChannel('files');+ await takeInEnginelessChange(event.relativePath);break;}case 'file-delete': {@@ -4412,6 +4432,22 @@ export function createServer(options: ServerOptions): ServerInstance {let watcher: WatcherHandle | null = null;+ function isEnginelessDoc(docName: string): boolean {+ return isMermaidDoc(docName) || isExcalidrawDoc(docName) || isEditableTextDoc(docName);+ }++ async function takeInEnginelessChange(docName: string): Promise<boolean> {+ if (!isEnginelessDoc(docName)) return false;+ const document = hocuspocus.documents.get(docName);+ if (!document) return false;+ const outcome = await applyExternalEnginelessChange(+ document,+ docName,+ persistence.mermaidPersistenceCtx,+ );+ return outcome !== 'unchanged';+ }+async function refreshDocumentsFromDisk(docNames: readonly string[],trigger: DocumentRefreshTrigger,@@ -4420,9 +4456,15 @@ export function createServer(options: ServerOptions): ServerInstance {const aliases = watcher.getAliasMap();const index = watcher.getFileIndex();const paths: string[] = [];+ const engineless = { checked: 0, found: 0 };for (const requested of new Set(docNames)) {const docName = aliases.get(requested) ?? requested;if (isReservedForUserTree(docName)) continue;+ if (isEnginelessDoc(docName)) {+ engineless.checked++;+ if (await takeInEnginelessChange(docName)) engineless.found++;+ continue;+ }const indexed = index.get(docName)?.canonicalPath;if (indexed !== undefined) {paths.push(indexed);@@ -4437,8 +4479,12 @@ export function createServer(options: ServerOptions): ServerInstance {);}}- if (paths.length === 0) return { checked: 0, found: 0 };- const result = await watcher.recheckPaths(paths);+ const rechecked =+ paths.length === 0 ? { checked: 0, found: 0 } : await watcher.recheckPaths(paths);+ const result = {+ checked: rechecked.checked + engineless.checked,+ found: rechecked.found + engineless.found,+ };const summary = { trigger, ...result };if (result.found > 0)log.info(summary, `[reconcile] re-read on ${trigger} found outside changes`);@@ -4466,7 +4512,9 @@ export function createServer(options: ServerOptions): ServerInstance {return 'lost';}try {- const ours = serializeDoc(docName);+ const ours = isPersistenceExcludedDoc(docName)+ ? (hocuspocus.documents.get(docName)?.getText('source').toString() ?? null)+ : serializeDoc(docName);if (ours === null) {log.warn({ docName, context },@@ -5300,7 +5348,7 @@ export function createServer(options: ServerOptions): ServerInstance {if (!absPath) continue;try {log.info({ docName: configDocName, path: absPath }, '[config-file-watcher] starting');- const cleanup = await startConfigFileWatcher(absPath, (content) => {+ const takeInConfigChange = async (content: string): Promise<void> => {const document = hocuspocus.documents.get(configDocName);const alreadyApplied = isConfigEcho(configDocName,@@ -5315,7 +5363,7 @@ export function createServer(options: ServerOptions): ServerInstance {},'[config-file-watcher] file changed',);- const outcome = applyExternalConfigChange(+ const outcome = await applyExternalConfigChange(document ?? null,configDocName,content,@@ -5329,6 +5377,14 @@ export function createServer(options: ServerOptions): ServerInstance {if (!alreadyApplied) {logConfigDiagnostics(configDocName);}+ };+ const cleanup = await startConfigFileWatcher(absPath, (content) => {+ void takeInConfigChange(content).catch((err: unknown) => {+ log.warn(+ { err, docName: configDocName },+ '[config-file-watcher] change handler failed',+ );+ });});configFileWatcherCleanups.push({ docName: configDocName, cleanup });configFileWatcherResyncs.set(configDocName, cleanup.resync);@@ -5353,11 +5409,11 @@ export function createServer(options: ServerOptions): ServerInstance {});}, 300);};- const reconcileManagedArtifactDisk = (absPath: string, content: string): void => {+ const reconcileManagedArtifactDisk = async (absPath: string, content: string) => {const docName = managedArtifactDocNameForPath(absPath, persistence.managedArtifactCtx);if (!docName) return;const document = hocuspocus.documents.get(docName);- const outcome = applyExternalManagedArtifactChange(+ const outcome = await applyExternalManagedArtifactChange(document ?? null,docName,content,@@ -5440,7 +5496,7 @@ export function createServer(options: ServerOptions): ServerInstance {if (changedPath === okignorePath) {try {const document = hocuspocus.documents.get(CONFIG_DOC_NAME_OKIGNORE) ?? null;- const outcome = applyExternalConfigChange(+ const outcome = await applyExternalConfigChange(document,CONFIG_DOC_NAME_OKIGNORE,content,diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.tsindex 66a775c97..a56d338e5 100644--- a/packages/server/src/shadow-repo.test.ts+++ b/packages/server/src/shadow-repo.test.ts@@ -1701,6 +1701,16 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)metadata: { side: 'theirs', reason: 'check-failed' },});return;+ case 'external-change-no-engine':+ await saveInMemoryCheckpoint(shadow, 'content/docs', {+ kind,+ docName: 'p.mmd',+ contents: `p${tag}\n`,+ label: 'l',+ date,+ metadata: { side: 'theirs', fileType: 'mermaid' },+ });+ return;case 'auto-consolidation':await writeAutoConsolidationCheckpoint(shadow, tag === '' ? 1 : Number(tag));return;@@ -1773,6 +1783,41 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)expect(remaining).toEqual([...quiet, ...busy.slice(3)].sort());});+ test('outside versions of files with no merge engine keep a per-document cap and never expire', async () => {+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ const seed = (docName: string, rank: number): Promise<string> =>+ saveInMemoryCheckpoint(shadow, 'content/docs', {+ kind: 'external-change-no-engine',+ docName,+ contents: `${docName} ${rank}\n`,+ label: 'l',+ date: seedDate(rank),+ metadata: { side: 'theirs', fileType: 'excalidraw' },+ });+ const quiet = await seed('quiet.excalidraw', 1);+ const busy: string[] = [];+ for (let rank = 2; rank <= 5; rank++) busy.push(await seed('busy.excalidraw', rank));++ const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxExternalChangeNoEnginePerDocument: 2,+ ttlMs: 1,+ });++ expect(result.deletedExternalChangeNoEngine).toBe(2);+ const remaining = (+ await shadowGit(shadow).raw(+ 'for-each-ref',+ '--format=%(objectname)',+ 'refs/checkpoints/main/',+ )+ )+ .trim()+ .split('\n')+ .sort();+ expect(remaining).toEqual([quiet, ...busy.slice(2)].sort());+ });+test('every registered kind is actually REAPED at its own limit, not merely bucketed', async () => {const { gcCheckpointRefs } = await import('./shadow-repo.ts');diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.tsindex 2d3e0d3d5..cd623f82c 100644--- a/packages/server/src/shadow-repo.ts+++ b/packages/server/src/shadow-repo.ts@@ -869,6 +869,14 @@ export type InMemoryCheckpointParams = (branch?: string;metadata: Extract<ParsedCheckpoint, { kind: 'external-change-kept-live' }>['metadata'];}+ | {+ kind: 'external-change-no-engine';+ docName: string;+ contents: string;+ label: string;+ branch?: string;+ metadata: Extract<ParsedCheckpoint, { kind: 'external-change-no-engine' }>['metadata'];+ }) & {date?: string;};@@ -1020,6 +1028,14 @@ async function saveInMemoryCheckpointInner(metadata: params.metadata,};break;+ case 'external-change-no-engine':+ parsed = {+ kind: 'external-change-no-engine',+ docName: params.docName,+ size,+ metadata: params.metadata,+ };+ break;}const bodyLine = formatCheckpointBodyLine(parsed);const message = `checkpoint: ${params.label}\n\n${bodyLine}`;@@ -1163,6 +1179,7 @@ export interface CheckpointRetentionPolicy {maxManagedArtifactReconcile: number;maxExternalChangeBothKeptPerDocument: number;maxExternalChangeKeptLivePerDocument: number;+ maxExternalChangeNoEnginePerDocument: number;maxAutoConsolidation: number;ttlMs: number;}@@ -1183,6 +1200,7 @@ export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {maxManagedArtifactReconcile: 50,maxExternalChangeBothKeptPerDocument: 50,maxExternalChangeKeptLivePerDocument: 50,+ maxExternalChangeNoEnginePerDocument: 50,maxAutoConsolidation: 2,ttlMs: 30 * 24 * 60 * 60 * 1000,};@@ -1204,6 +1222,7 @@ export interface CheckpointGcResult {deletedManagedArtifactReconcile: number;deletedExternalChangeBothKept: number;deletedExternalChangeKeptLive: number;+ deletedExternalChangeNoEngine: number;deletedAutoConsolidation: number;retained: number;}@@ -1308,6 +1327,12 @@ export const GC_BUCKET_POLICY = {applyTtl: false,scope: 'document',},+ 'external-change-no-engine': {+ limit: (p) => p.maxExternalChangeNoEnginePerDocument,+ counter: 'deletedExternalChangeNoEngine',+ applyTtl: false,+ scope: 'document',+ },'auto-consolidation': {limit: (p) => p.maxAutoConsolidation,counter: 'deletedAutoConsolidation',@@ -1346,6 +1371,7 @@ async function gcCheckpointRefsInner(deletedManagedArtifactReconcile: 0,deletedExternalChangeBothKept: 0,deletedExternalChangeKeptLive: 0,+ deletedExternalChangeNoEngine: 0,deletedAutoConsolidation: 0,retained: 0,};diff --git a/packages/server/src/stale-external-write-gate.test.ts b/packages/server/src/stale-external-write-gate.test.tsindex e7b54bbf3..25e02b777 100644--- a/packages/server/src/stale-external-write-gate.test.ts+++ b/packages/server/src/stale-external-write-gate.test.ts@@ -55,6 +55,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {async function settleWrite(agentTriggered = true): Promise<void> {writeFileSync(join(tmpDir, `${docName}.md`), STALE_CONTENT, 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -177,6 +178,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {writeFileSync(join(tmpDir, `${docName}.md`), STALE_CONTENT, 'utf-8');durabilityState.recordDisplacedVersion(docName, STALE_CONTENT);const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -301,6 +303,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {document.destroy();document = new Y.Doc();const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -328,6 +331,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {document = new Y.Doc();durabilityState = new DocumentDurabilityState('main', { persistencePath });const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -353,6 +357,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {writeFileSync(join(tmpDir, `${docName}.md`), STALE_CONTENT, 'utf-8');durabilityState.markAgentWriteStore(docName);const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -381,6 +386,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {document = new Y.Doc();const restoredState = new DocumentDurabilityState('main', { persistencePath });const restarted = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -461,6 +467,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {document = new Y.Doc();const restored = new DocumentDurabilityState('main', { persistencePath });const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,@@ -492,6 +499,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {projectDir: tmpDir,gitEnabled: false,durabilityState,+ mergeHistory: null,ingestDiskAtStore: async (name, _path, content) => {durabilityState.setReconciledBase(name, content);return { kind: 'taken-in' };@@ -511,6 +519,7 @@ describe('reconcileDiskBeforeAgentWrite — stale external write gate', () => {test('a blockless acknowledged base conflicts the pre-write reconcile and preserves the live doc', async () => {writeFileSync(join(tmpDir, `${docName}.md`), STALE_CONTENT, 'utf-8');const persistence = createPersistenceExtension({+ mergeHistory: null,ingestDiskAtStore: null,contentDir: tmpDir,projectDir: tmpDir,diff --git a/packages/server/src/store-compare.test.ts b/packages/server/src/store-compare.test.tsindex 769adf779..e67d37c4e 100644--- a/packages/server/src/store-compare.test.ts+++ b/packages/server/src/store-compare.test.ts@@ -16,6 +16,7 @@ import {compareDiskBeforeReplace,isTransientReadError,observationOf,+ readObservedText,receiptIntakeSkipOf,restatFile,} from './store-compare.ts';@@ -66,7 +67,20 @@ describe('compareDiskBeforeReplace', () => {test('a whitespace-only outside change the bridge normalizer tolerates is still a change', () => {writeFileSync(path, '# Doc\n\nagreed \n');- expect(compare()).toEqual({ kind: 'changed', text: '# Doc\n\nagreed \n' });+ expect(compare()).toEqual({+ kind: 'changed',+ text: '# Doc\n\nagreed \n',+ lossless: true,+ observation: observationOf(statSync(path, { bigint: true })),+ });+ });++ test('an outside change that is not valid UTF-8 is reported as not lossless', () => {+ writeFileSync(path, Buffer.from('\ufeffoutside\r\n', 'utf16le'));+ const outcome = compare();+ expect(outcome.kind).toBe('changed');+ if (outcome.kind !== 'changed') return;+ expect(outcome.lossless).toBe(false);});test('a line-ending-only outside change is a change', () => {@@ -140,6 +154,31 @@ describe('compareDiskBeforeReplace', () => {});});+describe('readObservedText', () => {+ test('reads the text with its observation, and says whether the bytes survive a UTF-8 round trip', () => {+ writeFileSync(path, 'caf\u00e9\n', 'utf-8');+ expect(readObservedText(path)).toEqual({+ kind: 'read',+ text: 'caf\u00e9\n',+ lossless: true,+ observation: observationOf(statSync(path, { bigint: true })),+ });++ writeFileSync(path, Buffer.from('caf\u00e9\n', 'latin1'));+ expect(readObservedText(path)).toMatchObject({ kind: 'read', lossless: false });+ });++ test('a missing file is absent and any other read error is a failure', () => {+ expect(readObservedText(join(dir, 'missing.md'))).toEqual({ kind: 'absent' });+ const failure = errno('EACCES');+ expect(+ readObservedText(path, () => {+ throw failure;+ }),+ ).toEqual({ kind: 'failed', error: failure });+ });+});+describe('isTransientReadError', () => {test.each([['EBUSY', 'linux', true],diff --git a/packages/server/src/store-compare.ts b/packages/server/src/store-compare.tsindex f7d8c6d03..808a05448 100644--- a/packages/server/src/store-compare.ts+++ b/packages/server/src/store-compare.ts@@ -44,7 +44,12 @@ export type DiskCompareOutcome =readonly alreadyCandidate: boolean;}| { readonly kind: 'drift'; readonly observation: FileObservation }- | { readonly kind: 'changed'; readonly text: string }+ | {+ readonly kind: 'changed';+ readonly text: string;+ readonly lossless: boolean;+ readonly observation: FileObservation;+ }| { readonly kind: 'absent' }| { readonly kind: 'unreadable'; readonly error: unknown; readonly transient: boolean };@@ -110,7 +115,43 @@ export function compareDiskBeforeReplace(if (input.baseHash !== undefined && diskHash === input.baseHash) {return { kind: 'drift', observation };}- return { kind: 'changed', text };+ return {+ kind: 'changed',+ text,+ lossless: Buffer.from(text, 'utf8').equals(observed.bytes),+ observation,+ };+}++export type ObservedTextRead =+ | {+ readonly kind: 'read';+ readonly text: string;+ readonly lossless: boolean;+ readonly observation: FileObservation;+ }+ | { readonly kind: 'absent' }+ | { readonly kind: 'failed'; readonly error: unknown };++export function readObservedText(+ path: string,+ read: (path: string) => ObservedFileRead = tracedReadObservedSync,+): ObservedTextRead {+ let observed: ObservedFileRead;+ try {+ observed = read(path);+ } catch (error) {+ const code = errnoCode(error);+ if (code !== undefined && ABSENT_CODES.has(code)) return { kind: 'absent' };+ return { kind: 'failed', error };+ }+ const text = observed.bytes.toString('utf8');+ return {+ kind: 'read',+ text,+ lossless: Buffer.from(text, 'utf8').equals(observed.bytes),+ observation: observationOf(observed.before),+ };}export type RestatOutcome =diff --git a/packages/server/src/timeline-query.test.ts b/packages/server/src/timeline-query.test.tsindex 818b41383..ec0620210 100644--- a/packages/server/src/timeline-query.test.ts+++ b/packages/server/src/timeline-query.test.ts@@ -26,6 +26,7 @@ import {parkBranch,SERVICE_WRITER,type ShadowHandle,+ saveInMemoryCheckpoint,saveVersion,type WriterIdentity,} from './shadow-repo';@@ -476,6 +477,30 @@ describe('getDocumentHistory', () => {expect(personal.entries).toHaveLength(0);});+ test('lists the history entries of a global skill, held in the open project shadow repo', async () => {+ const { shadow } = await setup();+ const docName = '__skill__/global/my-skill';+ const sha = await saveInMemoryCheckpoint(shadow, 'content/docs', {+ kind: 'external-change-both-kept',+ docName,+ contents: '# My Skill outside\n',+ label: 'Outside version before both versions were kept',+ metadata: { side: 'theirs', keptBlocks: 1 },+ });++ const all = await getDocumentHistory(shadow, { docName }, 'content/docs');+ expect(all.entries.map((e) => e.sha)).toEqual([sha]);++ const checkpoints = await getDocumentHistory(+ shadow,+ { docName, type: 'checkpoint' },+ 'content/docs',+ );+ expect(checkpoints.entries.map((e) => e.checkpoint?.kind)).toEqual([+ 'external-change-both-kept',+ ]);+ });+test('deduplicates entries that appear in multiple ref walks', async () => {const { contentDir, shadow } = await setup();diff --git a/packages/server/src/timeline-query.ts b/packages/server/src/timeline-query.tsindex f24a70bfc..0027d74e7 100644--- a/packages/server/src/timeline-query.ts+++ b/packages/server/src/timeline-query.ts@@ -329,7 +329,6 @@ export async function getDocumentHistory(const managed = query.docName? managedArtifactTimelinePaths(query.docName): ({ managed: false } as const);- if (managed.managed && !managed.versioned) return EMPTY;const managedFilePath = managed.managed && managed.versioned ? managed.filePath : undefined;const effectiveDocName = managed.managed && managed.versioned ? managed.docKey : query.docName;