Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): stop skill reconcile deleting symlinks it does not own (#2869)
tim-inkeep938077c70230
diff --git a/.changeset/reconcile-spares-foreign-symlinks.md b/.changeset/reconcile-spares-foreign-symlinks.mdnew file mode 100644index 000000000..84618c6ab--- /dev/null+++ b/.changeset/reconcile-spares-foreign-symlinks.md@@ -0,0 +1,9 @@+---+"@inkeep/open-knowledge": patch+---++Stop the boot-time skill reconcile from deleting or re-pointing symlinks it does not own.++The reconcile pass that runs on every server boot treated any editor-dir skill symlink (`.claude/skills`, `.codex/skills`, `.agents/skills`, etc.) whose name had no matching `.ok/skills/<name>` source as an orphan and removed it — without checking whether the link actually resolved. Repos that check in editor-dir symlinks pointing at their own shared skill store had every such link deleted on each boot, and a valid external link whose name collided with a `.ok/skills` entry was silently re-pointed. This happened regardless of the managed-skills opt-in.++A symlink whose target resolves to a real path outside `.ok/skills` is now classified as foreign and left untouched, mirroring the ownership boundary already applied to foreign real-dir skills. Dangling links and links into `.ok/skills` remain reconcile-managed exactly as before (healed when a source exists, removed when it does not).diff --git a/packages/server/src/skill-reconcile.test.ts b/packages/server/src/skill-reconcile.test.tsindex add4d9e27..b358bc2db 100644--- a/packages/server/src/skill-reconcile.test.ts+++ b/packages/server/src/skill-reconcile.test.ts@@ -93,6 +93,38 @@ describe('reconcileSkillInstalls', () => {expect(existsSync(link)).toBe(false);});+ test('leaves a symlink resolving outside .ok/skills untouched, even unmanaged', async () => {+ delete process.env.OK_SKILL_MANAGE; // the field failure needs no managed opt-in+ const shared = join(root, 'shared-skills', 'toolbox');+ mkdirSync(shared, { recursive: true });+ writeFileSync(join(shared, 'SKILL.md'), '---\nname: toolbox\n---\n# External');+ mkdirSync(join(root, '.agents', 'skills'), { recursive: true });+ const link = join(root, '.agents', 'skills', 'toolbox');+ symlinkSync(relative(join(root, '.agents', 'skills'), shared), link, 'dir');++ const r = await reconcileSkillInstalls({ projectDir: root, skillsRoot });+ expect(r.orphansRemoved).toEqual([]);+ expect(r.healed).toEqual([]);+ expect(r.skipped).toContainEqual({ name: 'toolbox', editor: null });+ expect(lstatSync(link).isSymbolicLink()).toBe(true);+ expect(readFileSync(join(link, 'SKILL.md'), 'utf-8')).toContain('# External');+ });++ test('does not re-point a foreign resolving symlink at a same-named .ok source', async () => {+ makeSource('toolbox', '# Managed');+ const shared = join(root, 'shared-skills', 'toolbox');+ mkdirSync(shared, { recursive: true });+ writeFileSync(join(shared, 'SKILL.md'), '---\nname: toolbox\n---\n# External');+ mkdirSync(join(root, '.codex', 'skills'), { recursive: true });+ const link = join(root, '.codex', 'skills', 'toolbox');+ symlinkSync(shared, link, 'dir');++ const r = await reconcileSkillInstalls({ projectDir: root, skillsRoot });+ expect(r.healed).toEqual([]);+ expect(r.skipped).toContainEqual({ name: 'toolbox', editor: 'codex' });+ expect(readFileSync(join(link, 'SKILL.md'), 'utf-8')).toContain('# External');+ });+test('adopts a foreign real-dir skill into .ok/skills and symlinks it + marks installed', async () => {makeEditorCopy('.codex/skills', 'recipe', '# Foreign body');diff --git a/packages/server/src/skill-reconcile.ts b/packages/server/src/skill-reconcile.tsindex 604d30f11..9fc691882 100644--- a/packages/server/src/skill-reconcile.ts+++ b/packages/server/src/skill-reconcile.ts@@ -12,8 +12,9 @@* |-------------------------------------------------|----------------|------------------------------|* | symlink → `.ok/skills/<name>` | managed | none |* | absent | not installed | none |- * | symlink, broken / wrong target, source present | drifted link | heal → re-point |- * | symlink, no `.ok/skills/<name>` source | orphan link | remove the dangling link |+ * | symlink → existing path outside `.ok/skills` | foreign link | leave untouched |+ * | symlink dangling or into `.ok/skills`, source present | drifted link | heal → re-point |+ * | symlink dangling or into `.ok/skills`, no source | orphan link | remove the dangling link |* | real dir, `.ok/skills/<name>` absent | foreign/legacy | adopt → move in + symlink *(only if project OK-managed; else leave untouched)* |* | real dir, source present, same content | redundant copy | replace with a symlink |* | real dir, same skill (frontmatter-only diff) | redundant copy | replace with a symlink |@@ -25,6 +26,10 @@* `skill-management.ts`). Off ⇒ the foreign editor entry is left untouched* (`result.skipped`). Membership in `.ok/skills` is the ownership boundary: every* other row manages a skill OK already owns and runs regardless of the gate.+ * The same boundary governs symlinks: a link whose target resolves to a real+ * path OUTSIDE `.ok/skills` (e.g. a repo that checks editor-dir links into its+ * own shared skill store) is foreign and is never healed or removed — only+ * dangling links and links into `.ok/skills` are reconcile-managed.** "Same content" is byte-equality; "same skill" additionally treats two copies* as one when their SKILL.md differs only in frontmatter serialization (folded@@ -96,10 +101,12 @@ export interface ReconcileResult {collided: ReconcileAction[];orphansRemoved: ReconcileAction[];/**- * Foreign editor-dir skills (no `.ok/skills/<name>` source, or a colliding- * different skill) left UNTOUCHED because the project is not OK-managed- * (`manageEditorSkills` off). These would have been adopted/suffix-adopted only- * after an explicit import opt-in — see `skill-management.ts`.+ * Foreign editor-dir skills left UNTOUCHED: real dirs (no `.ok/skills/<name>`+ * source, or a colliding different skill) skipped because the project is not+ * OK-managed (`manageEditorSkills` off — these would have been adopted/+ * suffix-adopted only after an explicit import opt-in, see+ * `skill-management.ts`), and symlinks resolving to a real path outside+ * `.ok/skills` (skipped unconditionally — OK does not own them).*/skipped: ReconcileAction[];}@@ -274,6 +281,32 @@ function pointsAtSource(linkPath: string, sourceDir: string): boolean {}}+/**+ * Is this symlink a FOREIGN install — a link whose target resolves to a real+ * path outside `.ok/skills`? Such links are user/repo-managed (e.g. a monorepo+ * checks editor-dir links into its own shared skill store); reconcile must+ * neither remove them as orphans nor re-point them at a same-named `.ok`+ * source. Dangling links and links into `.ok/skills` return false and stay+ * reconcile-managed.+ */+function isForeignSymlink(linkPath: string, skillsRoot: string): boolean {+ try {+ const raw = readlinkSync(linkPath);+ const target = isAbsolute(raw) ? resolve(raw) : resolve(dirname(linkPath), raw);+ if (!existsSync(target)) return false; // dangling — reconcile-managed+ const rel = relative(resolve(skillsRoot), target);+ return rel !== '' && (rel.startsWith('..') || isAbsolute(rel));+ } catch (err) {+ // Unreadable link (EACCES/EIO) falls through to the heal/orphan path,+ // which may delete it — log so that outcome is traceable to its cause.+ logger.warn(+ { linkPath, err },+ 'isForeignSymlink: could not resolve symlink; treating as reconcile-managed',+ );+ return false;+ }+}+/*** Count the distinct editor-dir skills that an import would ADOPT — real-dir* skills (valid name, not OK's shipped bundle) that are NOT already a managed /@@ -312,8 +345,8 @@ export function countImportableEditorSkills(opts: {} catch {continue;}- // Only real dirs are import candidates — symlinks are already managed- // (or orphan links handled by reconcile), never adopted.+ // Only real dirs are import candidates — symlinks are either managed,+ // foreign (left untouched), or orphans handled by reconcile; never adopted.if (stat.isSymbolicLink() || !stat.isDirectory()) continue;const sourceDir = resolve(skillsRoot, name);if (@@ -390,6 +423,10 @@ export async function reconcileSkillInstalls(opts: {const stat = lstatSync(entryPath);if (stat.isSymbolicLink()) {if (pointsAtSource(entryPath, sourceDir) && sourceExists) continue; // managed, OK+ if (isForeignSymlink(entryPath, skillsRoot)) {+ result.skipped.push({ name, editor }); // foreign link — not OK's to manage+ continue;+ }if (sourceExists) {linkInto(hostRoot, entryPath, sourceDir); // heal drifted linkresult.healed.push({ name, editor });diff --git a/test-support/bun-global-shim.test.ts b/test-support/bun-global-shim.test.tsindex c256a02eb..f7dcd9e35 100644--- a/test-support/bun-global-shim.test.ts+++ b/test-support/bun-global-shim.test.ts@@ -1,4 +1,5 @@import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { stripTypeScriptTypes } from 'node:module';import { tmpdir } from 'node:os';import { join } from 'node:path';import { fileURLToPath } from 'node:url';@@ -89,12 +90,25 @@ describe('Bun global facade', () => {test('Bun.Transpiler compiles TypeScript and throws on a syntax error', () => {const transpiler = new bunFacade.Transpiler({ loader: 'ts' });- const out = transpiler.transformSync('const x: number = 1;\nenum E { A, B }\n');- // Type annotation erased; the enum lowered to real JavaScript.+ const out = transpiler.transformSync('const x: number = 1;\n');+ // Type annotation erased.expect(out).not.toContain(': number');- expect(out).toContain('E');- expect(out).toContain('const x = 1');+ expect(out).toContain('const x');expect(() => transpiler.transformSync('const = ;')).toThrow();+ // Enum lowering needs `transform` mode; on strip-only runtimes (Node 26)+ // the facade falls back and TS-only constructs throw instead of compiling.+ let transformAvailable = true;+ try {+ stripTypeScriptTypes('0', { mode: 'transform' });+ } catch {+ transformAvailable = false;+ }+ const enumSource = 'enum E { A, B }\n';+ if (transformAvailable) {+ expect(transpiler.transformSync(enumSource)).toContain('E');+ } else {+ expect(() => transpiler.transformSync(enumSource)).toThrow();+ }});test('which/sleep/spawnSync/gc behave on Node', async () => {diff --git a/test-support/bun-global-shim.ts b/test-support/bun-global-shim.tsindex b8aa9d8c9..518795418 100644--- a/test-support/bun-global-shim.ts+++ b/test-support/bun-global-shim.ts@@ -400,15 +400,27 @@ class BunCryptoHasherFacade {* syntax error. Node's `stripTypeScriptTypes` in `transform` mode is the* dependency-free equivalent: it compiles TS-only constructs (enums, parameter* properties) rather than only erasing annotations, and throws on invalid- * syntax — the property the callers assert. Only the sync path the suites use- * is provided.+ * syntax — the property the callers assert. Node 26 ships strip-only+ * (`transform` is rejected with ERR_INVALID_ARG_VALUE), so fall back to+ * `strip` there: annotations still erase and invalid syntax still throws;+ * only TS-only constructs — which no caller feeds in — throw instead of+ * compiling. Only the sync path the suites use is provided.*/+function transpileTs(code: string): string {+ try {+ return stripTypeScriptTypes(code, { mode: 'transform' });+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code !== 'ERR_INVALID_ARG_VALUE') throw err;+ return stripTypeScriptTypes(code, { mode: 'strip' });+ }+}+class BunTranspilerFacade {transformSync(code: string): string {- return stripTypeScriptTypes(code, { mode: 'transform' });+ return transpileTs(code);}async transform(code: string): Promise<string> {- return stripTypeScriptTypes(code, { mode: 'transform' });+ return transpileTs(code);}}