Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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 link
result.healed.push({ name, editor });
diff --git a/test-support/bun-global-shim.test.ts b/test-support/bun-global-shim.test.ts
index 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.ts
index 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);
}
}