@thesmurph/agentlink 0.1.0

package/dist/harnesses.js

@@ -0,0 +1,206 @@
+export function endpointVerified(endpoint) {
+    return endpoint.verified !== false;
+}
+/** Endpoints in a scope that no vendor documentation confirms. */
+export function unverifiedEndpoints(harness, scope) {
+    const found = [];
+    for (const kind of ["instructions", "skills"]) {
+        const endpoint = harness[kind][scope];
+        if (!endpointVerified(endpoint))
+            found.push({ kind, endpoint });
+    }
+    return found;
+}
+const PI_SKILLS_DOC = "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md";
+const CODEX_SKILLS_DOC = "https://developers.openai.com/codex/skills";
+const CLAUDE_SKILLS_DOC = "https://code.claude.com/docs/en/skills";
+const COPILOT_SKILLS_DOC = "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills";
+const COPILOT_INSTRUCTIONS_DOC = "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions";
+/** Build a endpoints pair: project + global in one call. */
+function scopes(project, global) {
+    return { project, global };
+}
+const NATIVE = { native: true };
+export const HARNESSES = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        bins: ["claude"],
+        configRoot: ".claude",
+        // Claude Code reads CLAUDE.md, not AGENTS.md, and never scans .agents/skills.
+        instructions: scopes({ native: false, alias: "CLAUDE.md", note: "Claude Code has no AGENTS.md fallback" }, { native: false, alias: ".claude/CLAUDE.md" }),
+        skills: scopes({ native: false, alias: ".claude/skills" }, { native: false, alias: ".claude/skills" }),
+        source: CLAUDE_SKILLS_DOC,
+    },
+    {
+        id: "codex",
+        label: "OpenAI Codex CLI",
+        bins: ["codex"],
+        configRoot: ".codex",
+        // Codex reads AGENTS.md in the repo and ~/.codex/AGENTS.md globally.
+        instructions: scopes({ native: true }, { native: false, alias: ".codex/AGENTS.md" }),
+        // Codex's user-level skills directory is $HOME/.agents/skills: native both ways.
+        skills: scopes(NATIVE, NATIVE),
+        source: CODEX_SKILLS_DOC,
+    },
+    {
+        id: "pi",
+        label: "Pi",
+        bins: ["pi"],
+        configRoot: ".pi",
+        instructions: scopes({ native: true }, { native: false, alias: ".pi/agent/AGENTS.md" }),
+        // Pi reads ~/.agents/skills and .agents/skills directly.
+        skills: scopes(NATIVE, NATIVE),
+        source: PI_SKILLS_DOC,
+    },
+    {
+        id: "omp",
+        label: "Oh My Pi (omp)",
+        bins: ["omp"],
+        configRoot: ".omp",
+        instructions: scopes({ native: true, note: "standalone AGENTS.md via the agents-md provider" }, { native: false, alias: ".omp/agent/AGENTS.md" }),
+        // omp scans its own .omp/skills trees; it does not read .agents/skills.
+        skills: scopes({ native: false, alias: ".omp/skills" }, { native: false, alias: ".omp/agent/skills" }),
+        source: "https://github.com/can1357/oh-my-pi/blob/main/docs/config-usage.md",
+    },
+    {
+        id: "copilot",
+        label: "GitHub Copilot CLI",
+        bins: ["copilot"],
+        configRoot: ".copilot",
+        // Copilot CLI reads AGENTS.md everywhere, but its *user* instructions live
+        // in a differently named file.
+        instructions: scopes({ native: true }, { native: false, alias: ".copilot/copilot-instructions.md" }),
+        skills: scopes(NATIVE, NATIVE),
+        source: `${COPILOT_SKILLS_DOC} · ${COPILOT_INSTRUCTIONS_DOC}`,
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        bins: ["cursor-agent", "cursor"],
+        configRoot: ".cursor",
+        instructions: scopes({ native: true, note: "Cursor reads AGENTS.md" }, { native: false, alias: ".cursor/AGENTS.md", note: "not documented by Cursor", verified: false }),
+        skills: scopes({ native: false, alias: ".cursor/skills", verified: false }, { native: false, alias: ".cursor/skills", verified: false }),
+        source: "https://cursor.com/docs/agent/context",
+    },
+    {
+        id: "opencode",
+        label: "opencode",
+        bins: ["opencode"],
+        configRoot: ".config/opencode",
+        instructions: scopes({ native: true }, { native: false, alias: ".config/opencode/AGENTS.md" }),
+        skills: scopes({ native: false, alias: ".opencode/skills", verified: false }, { native: false, alias: ".config/opencode/skills", verified: false }),
+        source: "https://opencode.ai/docs/rules/",
+    },
+    {
+        id: "qwen",
+        label: "Qwen Code",
+        bins: ["qwen"],
+        configRoot: ".qwen",
+        instructions: scopes({ native: true, note: "QWEN.md is the legacy name" }, { native: false, alias: ".qwen/AGENTS.md", note: "not documented by Qwen", verified: false }),
+        skills: scopes({ native: false, alias: ".qwen/skills" }, { native: false, alias: ".qwen/skills" }),
+        source: "https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/",
+    },
+    {
+        id: "kimi",
+        label: "Kimi Code CLI",
+        bins: ["kimi"],
+        configRoot: ".kimi-code",
+        instructions: scopes({ native: true }, { native: false, alias: ".kimi-code/AGENTS.md", note: "not documented by Kimi", verified: false }),
+        skills: scopes({ native: false, alias: ".kimi-code/skills" }, NATIVE),
+        source: "https://www.kimi.com/code/docs/en/kimi-code-cli/customization/skills.html",
+    },
+    {
+        id: "kilo",
+        label: "Kilo Code",
+        bins: ["kilo"],
+        configRoot: ".config/kilo",
+        instructions: scopes({ native: true }, { native: false, alias: ".config/kilo/AGENTS.md", note: "not documented by Kilo" }),
+        // Kilo Code reads Claude Code's skills directory for compatibility.
+        skills: scopes({ native: false, alias: ".claude/skills", note: "shares Claude Code's directory", verified: false }, { native: false, alias: ".config/kilo/skills", note: "unconfirmed", verified: false }),
+        source: "https://github.com/intellectronica/ruler#skills-support-experimental",
+    },
+    {
+        id: "droid",
+        label: "Factory Droid",
+        bins: ["droid"],
+        configRoot: ".factory",
+        instructions: scopes({ native: true, note: "AGENTS.md may also live in the home directory" }, { native: false, alias: ".factory/AGENTS.md" }),
+        skills: scopes({ native: false, alias: ".factory/skills" }, { native: false, alias: ".factory/skills" }),
+        source: "https://docs.factory.ai/harness/skills",
+    },
+    {
+        id: "devin",
+        label: "Devin CLI",
+        bins: ["devin"],
+        configRoot: ".config/devin",
+        instructions: scopes({ native: true }, { native: false, alias: ".config/devin/AGENTS.md" }),
+        skills: scopes({ native: false, alias: ".devin/skills" }, { native: false, alias: ".config/devin/skills" }),
+        source: "https://docs.devin.ai/cli/extensibility/rules",
+    },
+    {
+        id: "mastracode",
+        label: "Mastra Code",
+        bins: ["mastracode"],
+        configRoot: ".mastracode",
+        instructions: scopes({ native: true }, { native: false, alias: ".mastracode/AGENTS.md", note: "not documented by Mastra", verified: false }),
+        // Mastra Code lists .agents/skills as a project source and Agent Skills
+        // spec compatibility, so both scopes are native.
+        skills: scopes(NATIVE, NATIVE),
+        source: "https://code.mastra.ai/configuration",
+    },
+    {
+        id: "grok",
+        label: "Grok CLI",
+        bins: ["grok"],
+        configRoot: ".grok",
+        instructions: scopes({ native: true, note: "reads AGENTS.md, CLAUDE.md, AGENT.md" }, { native: false, alias: ".grok/AGENTS.md", note: "not documented by Grok", verified: false }),
+        skills: scopes({ native: false, alias: ".grok/skills" }, { native: false, alias: ".grok/skills" }),
+        source: "https://docs.x.ai/docs/grok-cli/skills",
+    },
+    {
+        id: "qoder",
+        label: "Qoder CLI",
+        bins: ["qodercli", "qoder"],
+        configRoot: ".qoder",
+        instructions: scopes({ native: true, note: "configurable via context.fileName" }, { native: false, alias: ".qoder/AGENTS.md", note: "not documented by Qoder", verified: false }),
+        skills: scopes({ native: false, alias: ".qoder/skills" }, { native: false, alias: ".qoder/skills" }),
+        source: "https://docs.qoder.com/cli/Skills",
+    },
+    {
+        id: "antigravity",
+        label: "Antigravity CLI",
+        bins: ["agy", "antigravity"],
+        configRoot: ".gemini/config",
+        instructions: scopes({ native: true, note: "Gemini-lineage discovery: AGENTS.md, CONTEXT.md, GEMINI.md", verified: false }, { native: false, alias: ".gemini/config/AGENTS.md", note: "unconfirmed", verified: false }),
+        skills: scopes({ native: false, alias: ".agent/skills", note: "unconfirmed", verified: false }, { native: false, alias: ".gemini/config/skills", note: "unconfirmed", verified: false }),
+        source: "https://github.com/intellectronica/ruler#skills-support-experimental",
+    },
+    {
+        id: "hermes",
+        label: "Hermes",
+        bins: ["hermes"],
+        configRoot: ".hermes",
+        instructions: scopes({ native: true, note: "unconfirmed", verified: false }, { native: false, alias: ".hermes/AGENTS.md", note: "unconfirmed" }),
+        skills: scopes({ native: false, alias: ".hermes/skills", note: "unconfirmed", verified: false }, { native: false, alias: ".hermes/skills", note: "unconfirmed", verified: false }),
+        source: "https://herdr.dev/llms.txt",
+    },
+];
+export const HARNESS_IDS = HARNESSES.map((h) => h.id);
+export function findHarness(id) {
+    const needle = id.trim().toLowerCase();
+    return HARNESSES.find((h) => h.id === needle || h.label.toLowerCase() === needle);
+}
+/** Resolve a comma/space separated harness list; unknown ids are returned to the caller. */
+export function resolveHarnessList(input) {
+    const found = [];
+    const unknown = [];
+    for (const raw of input.split(/[,\s]+/).filter(Boolean)) {
+        const harness = findHarness(raw);
+        if (harness)
+            found.push(harness);
+        else
+            unknown.push(raw);
+    }
+    return { found, unknown };
+}

package/dist/ignore.js

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "./link.js";
+/** Matched as whole lines: a user comment like "# agentlink:beginning" is not our marker. */
+const BEGIN_LINE = /^# agentlink:begin\s*$/m;
+const END_LINE = /^# agentlink:end\s*$/m;
+const BLOCK = "# agentlink:begin";
+export const IGNORE_MODES = ["skills", "all", "none"];
+export function isIgnoreMode(value) {
+    return IGNORE_MODES.includes(value);
+}
+/**
+ * Which created links belong in .gitignore.
+ *
+ * Instructions aliases are one small file per harness and are the thing that
+ * makes a fresh clone work for a teammate on a different harness, so they are
+ * committed. Skill links are derived, multiply with every skill and harness,
+ * and their parent directories also hold machine-local harness state, so they
+ * are ignored and regenerated by `agentlink sync`.
+ */
+export function ignoreEntries(mode, input) {
+    const entries = [];
+    if (mode === "none")
+        return entries;
+    for (const dir of input.skillDirs)
+        entries.push(`${dir}/`);
+    if (mode === "all")
+        entries.push(...input.instructionFiles);
+    return [...new Set(entries)].sort();
+}
+export function updateGitignore(paths, mode, input, options = {}) {
+    const file = path.join(paths.root, ".gitignore");
+    const entries = ignoreEntries(mode, input);
+    // Only touch a repository that actually tracks files here.
+    if (paths.scope !== "project" || !existsSync(path.join(paths.root, ".git"))) {
+        return { status: "unchanged", file, entries, skipped: "not a git repository" };
+    }
+    const before = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const spliced = applyIgnoreBlock(before, entries);
+    if (spliced.status === "malformed")
+        return { status: spliced.status, file, entries };
+    const changed = spliced.status === "updated";
+    if (changed && !options.dryRun)
+        writeFileAtomic(file, spliced.text);
+    return { status: spliced.status, file, entries };
+}
+/** Remove the managed block, leaving the rest of .gitignore alone. */
+export function removeIgnoreBlock(paths, options = {}) {
+    const file = path.join(paths.root, ".gitignore");
+    if (!existsSync(file))
+        return false;
+    const before = readFileSync(file, "utf8");
+    const spliced = applyIgnoreBlock(before, []);
+    if (spliced.status !== "updated" || spliced.text === before)
+        return false;
+    if (!options.dryRun)
+        writeFileAtomic(file, spliced.text);
+    return true;
+}
+/** Read the entries currently inside the managed block. */
+export function readIgnoreBlock(paths) {
+    const text = existsSync(path.join(paths.root, ".gitignore"))
+        ? readFileSync(path.join(paths.root, ".gitignore"), "utf8")
+        : "";
+    return blockSpan(text)?.entries ?? [];
+}
+/** Locate the managed block by whole-line markers. Returns null when absent. */
+function blockSpan(text) {
+    const begin = BEGIN_LINE.exec(text);
+    if (!begin)
+        return null;
+    const afterBegin = begin.index + begin[0].length;
+    const end = END_LINE.exec(text.slice(afterBegin));
+    if (!end)
+        return null;
+    const endIndex = afterBegin + end.index;
+    const body = text.slice(afterBegin, endIndex);
+    return {
+        start: begin.index,
+        end: endIndex + end[0].length,
+        entries: body
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith("#")),
+    };
+}
+/**
+ * Insert, replace or remove the managed block.
+ *
+ * Text outside the block is never rewritten: no whitespace normalisation runs
+ * over the user's file. A lone marker is refused rather than guessed at, since
+ * anything after an unterminated block might be the user's own rules.
+ */
+export function applyIgnoreBlock(text, entries) {
+    const beginMatch = BEGIN_LINE.exec(text);
+    const endMatch = END_LINE.exec(text);
+    if (beginMatch && !endMatch) {
+        return { text, status: "malformed" };
+    }
+    if (!beginMatch && endMatch) {
+        return { text, status: "malformed" };
+    }
+    const span = beginMatch && endMatch ? blockSpan(text) : null;
+    const without = span ? `${text.slice(0, span.start)}${text.slice(span.end)}` : text;
+    if (entries.length === 0) {
+        if (!span)
+            return { text, status: "unchanged" };
+        // Remove the blank line the block was separated by, but nothing else.
+        const trimmed = without.replace(/\n[ \t]*\n$/, "\n").replace(/\n$/, text.endsWith("\n") ? "\n" : "");
+        return { text: trimmed, status: "updated" };
+    }
+    const block = [BLOCK, ...entries, "# agentlink:end"].join("\n");
+    if (span) {
+        const next = `${without.slice(0, span.start)}${block}\n${without.slice(span.start).replace(/^\n/, "")}`;
+        return { text: next, status: next === text ? "unchanged" : "updated" };
+    }
+    const base = text.replace(/\s+$/, "");
+    const next = base === "" ? `${block}\n` : `${base}\n\n${block}\n`;
+    return { text: next, status: next === text ? "unchanged" : "updated" };
+}

package/dist/link.js

@@ -0,0 +1,307 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmdirSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { listSubdirectories, relativeTo } from "./scope.js";
+/** True when `dir` resolves to the same place as the canonical skills tree. */
+function resolvesToCanonicalSkills(paths, dir) {
+    try {
+        return realpathSync(dir) === realpathSync(paths.skills);
+    }
+    catch {
+        return false;
+    }
+}
+/** Build the full set of links for a scope without touching the filesystem. */
+export function plan(paths, harnesses) {
+    const ops = new Map();
+    const skips = [];
+    const native = [];
+    const unknown = [];
+    const aliases = [];
+    const add = (op, harnessId) => {
+        const existing = ops.get(op.target);
+        if (existing) {
+            if (!existing.harnessIds.includes(harnessId))
+                existing.harnessIds.push(harnessId);
+            return;
+        }
+        ops.set(op.target, { ...op, harnessIds: [harnessId] });
+    };
+    const skip = (op, harnessId) => {
+        const existing = skips.find((s) => s.target === op.target && s.reason === op.reason);
+        if (existing) {
+            if (!existing.harnessIds.includes(harnessId))
+                existing.harnessIds.push(harnessId);
+            return;
+        }
+        skips.push({ ...op, harnessIds: [harnessId] });
+    };
+    const instructionsExist = existsSync(paths.instructions);
+    const skills = listSubdirectories(paths.skills);
+    for (const harness of harnesses) {
+        const instr = harness.instructions[paths.scope];
+        const alias = instr.native ? undefined : instr.alias;
+        if (instr.native) {
+            native.push({ harnessId: harness.id, kind: "instructions" });
+        }
+        else if (!alias) {
+            unknown.push({ harnessId: harness.id, kind: "instructions" });
+        }
+        else if (!instructionsExist) {
+            skip({
+                target: path.join(paths.root, alias),
+                rel: alias,
+                kind: "instructions",
+                reason: "AGENTS.md does not exist yet — run `agentlink init` first",
+            }, harness.id);
+        }
+        else {
+            add({
+                target: path.join(paths.root, alias),
+                source: paths.instructions,
+                rel: alias,
+                kind: "instructions",
+            }, harness.id);
+        }
+        const sk = harness.skills[paths.scope];
+        const skillsAlias = sk.native ? undefined : sk.alias;
+        if (sk.native) {
+            native.push({ harnessId: harness.id, kind: "skill" });
+        }
+        else if (!skillsAlias) {
+            unknown.push({ harnessId: harness.id, kind: "skill" });
+        }
+        else if (resolvesToCanonicalSkills(paths, path.join(paths.root, skillsAlias))) {
+            // The harness directory is a symlink to .agents/skills, which is already
+            // the arrangement this tool exists to create.
+            aliases.push({ rel: skillsAlias, harnessId: harness.id });
+        }
+        else if (skills.length === 0) {
+            skip({
+                target: path.join(paths.root, skillsAlias),
+                rel: skillsAlias,
+                kind: "skill",
+                reason: "no skills in .agents/skills yet",
+            }, harness.id);
+        }
+        else {
+            for (const skill of skills) {
+                add({
+                    target: path.join(paths.root, skillsAlias, skill),
+                    source: path.join(paths.skills, skill),
+                    rel: path.posix.join(skillsAlias, skill),
+                    kind: "skill",
+                    skill,
+                }, harness.id);
+            }
+        }
+    }
+    return { ops: [...ops.values()], skips, native, unknown, aliases, skillsFound: skills };
+}
+/**
+ * Apply a plan. Each op is isolated: one failure is reported as skipped rather
+ * than aborting the batch, so links created earlier stay recorded in state and
+ * remain removable by `unlink`.
+ */
+export function apply(paths, plan, options = {}) {
+    return plan.ops.map((op) => {
+        try {
+            return createLink(paths, op, options);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { op, state: "skipped", detail: `could not link: ${message}` };
+        }
+    });
+}
+function createLink(paths, op, options) {
+    const existing = inspect(op.target);
+    if (existing.kind === "error") {
+        return { op, state: "skipped", detail: `cannot inspect: ${existing.detail}` };
+    }
+    if (existing.kind === "missing") {
+        if (!options.dryRun) {
+            mkdirSync(path.dirname(op.target), { recursive: true });
+            symlinkSync(relativeTo(path.dirname(op.target), op.source), op.target);
+        }
+        return { op, state: "linked" };
+    }
+    if (existing.kind === "symlink") {
+        if (existing.resolved === op.source)
+            return { op, state: "unchanged" };
+        if (isOwned(paths, existing.resolved)) {
+            if (!options.dryRun) {
+                unlinkSync(op.target);
+                symlinkSync(relativeTo(path.dirname(op.target), op.source), op.target);
+            }
+            return { op, state: "relinked" };
+        }
+        return { op, state: "skipped", detail: `already a symlink to ${existing.resolved}` };
+    }
+    return { op, state: "skipped", detail: blockerMessage(op, existing.kind) };
+}
+function blockerMessage(op, kind) {
+    if (op.kind === "instructions") {
+        return kind === "dir"
+            ? `a directory sits at ${op.rel} — remove it, or point it at AGENTS.md yourself`
+            : `a real instructions file sits here — merge it into AGENTS.md and re-run`;
+    }
+    return kind === "dir"
+        ? "a real directory sits here — run `agentlink fix` to fold it into .agents/skills"
+        : "a real file sits here — remove it and re-run";
+}
+/**
+ * True when agentlink created a path: the canonical AGENTS.md it links aliases
+ * to, or anything inside <root>/.agents. Only these are safe to replace/delete.
+ */
+function isOwned(paths, target) {
+    if (!target)
+        return false;
+    if (target === paths.instructions)
+        return true;
+    const owned = `${paths.agentsDir}${path.sep}`;
+    return target === paths.agentsDir || target.startsWith(owned);
+}
+/** True when `target` is inside `root` after normalisation. */
+export function isInside(root, target) {
+    const resolved = path.resolve(root, target);
+    return resolved === root || resolved.startsWith(`${root}${path.sep}`);
+}
+export function inspect(target) {
+    let stat;
+    try {
+        stat = lstatSync(target);
+    }
+    catch (error) {
+        const code = error?.code;
+        // Anything other than "does not exist" (ENOTDIR, EACCES, ELOOP, …) is a
+        // real problem the caller must report rather than paper over by writing.
+        if (code === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "error", detail: `${code ?? "unknown error"}` };
+    }
+    if (stat.isSymbolicLink()) {
+        return { kind: "symlink", resolved: path.resolve(path.dirname(target), readlinkSync(target)) };
+    }
+    return { kind: stat.isDirectory() ? "dir" : "file" };
+}
+export function readState(paths) {
+    try {
+        const parsed = JSON.parse(readFileSync(paths.stateFile, "utf8"));
+        if (parsed?.version === 1) {
+            return {
+                version: 1,
+                scope: parsed.scope ?? paths.scope,
+                harnesses: parsed.harnesses ?? [],
+                ignore: parsed.ignore ?? "skills",
+                // A hand-edited or hostile state file must not let a later unlink reach
+                // outside the scope root.
+                links: (parsed.links ?? []).filter((link) => typeof link?.path === "string" && isInside(paths.root, link.path)),
+            };
+        }
+    }
+    catch {
+        /* first run */
+    }
+    return { version: 1, scope: paths.scope, harnesses: [], ignore: "skills", links: [] };
+}
+export function writeState(paths, state) {
+    mkdirSync(paths.agentsDir, { recursive: true });
+    writeFileAtomic(paths.stateFile, `${JSON.stringify(state, null, 2)}\n`);
+}
+/** Write via a temp file and rename, so an interrupted run cannot truncate. */
+export function writeFileAtomic(file, contents) {
+    const temporary = `${file}.agentlink-tmp`;
+    writeFileSync(temporary, contents, "utf8");
+    renameSync(temporary, file);
+}
+/**
+ * Remove links agentlink owns that the current plan no longer wants: a
+ * deselected harness, or a skill that was renamed or deleted. Without this the
+ * old symlinks stay behind and dangle.
+ */
+export function pruneStale(paths, plan, previous, options = {}) {
+    const wanted = new Set(plan.ops.map((op) => op.rel));
+    const removed = [];
+    for (const link of previous.links) {
+        if (wanted.has(link.path) || !isInside(paths.root, link.path))
+            continue;
+        const target = path.join(paths.root, link.path);
+        const existing = inspect(target);
+        if (existing.kind !== "symlink" || !isOwned(paths, existing.resolved))
+            continue;
+        if (!options.dryRun) {
+            unlinkSync(target);
+            pruneEmptyParents(path.dirname(target), paths.root);
+        }
+        removed.push(link.path);
+    }
+    return removed;
+}
+/** Fold this run's results into the previous state. */
+export function mergeState(paths, previous, results, harnessIds, options = {}) {
+    const planned = options.plannedRels ? new Set(options.plannedRels) : undefined;
+    const links = new Map(previous.links.filter((link) => !planned || planned.has(link.path)).map((link) => [link.path, link]));
+    for (const result of results) {
+        if (result.state === "skipped")
+            continue;
+        links.set(result.op.rel, {
+            path: result.op.rel,
+            source: relativeTo(paths.root, result.op.source),
+        });
+    }
+    return {
+        version: 1,
+        scope: paths.scope,
+        harnesses: harnessIds,
+        ignore: options.ignore ?? previous.ignore ?? "skills",
+        links: [...links.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    };
+}
+/**
+ * Remove the symlinks agentlink created. Anything that is no longer a symlink
+ * pointing into .agents is left alone and reported instead.
+ */
+export function unlink(paths, options = {}) {
+    const state = readState(paths);
+    const removed = [];
+    const kept = [];
+    for (const link of state.links) {
+        if (!isInside(paths.root, link.path)) {
+            kept.push({ path: link.path, reason: "outside this scope" });
+            continue;
+        }
+        const target = path.join(paths.root, link.path);
+        const existing = inspect(target);
+        if (existing.kind === "missing")
+            continue;
+        if (existing.kind !== "symlink") {
+            kept.push({ path: link.path, reason: `no longer a symlink (real ${existing.kind})` });
+            continue;
+        }
+        if (!isOwned(paths, existing.resolved)) {
+            kept.push({ path: link.path, reason: "points outside .agents now" });
+            continue;
+        }
+        if (!options.dryRun) {
+            unlinkSync(target);
+            pruneEmptyParents(path.dirname(target), paths.root);
+        }
+        removed.push(link.path);
+    }
+    if (!options.dryRun)
+        writeState(paths, { ...state, links: [] });
+    return { removed, kept };
+}
+export function pruneEmptyParents(dir, root) {
+    let current = dir;
+    while (current !== root && current.startsWith(`${root}${path.sep}`)) {
+        try {
+            rmdirSync(current);
+        }
+        catch {
+            return;
+        }
+        current = path.dirname(current);
+    }
+}
+export { isOwned };