agent-trellis 0.1.0

package/dist/adapters/kiro.js

@@ -0,0 +1,175 @@
+/**
+ * Kiro adapter: same shape as Claude Code — `~/.kiro/skills/<name>`
+ * symlinks, `~/.kiro/steering/CLAUDE.md` symlinked to canonical `agents.md`.
+ *
+ * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
+ * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
+ * removal (D7).
+ *
+ * Kiro's own `${VAR}` substitution (real, found by reading Kiro's
+ * installed extension source — trellis-kiro-approved-env-vars design.md
+ * Context) is gated by `kiroAgent.mcpApprovedEnvVars`, a completely
+ * separate, VS-Code-style global settings.json — not the mcp.json above.
+ * A name absent from that list is silently never substituted. This
+ * adapter keeps that list a superset of every env name it references,
+ * additive only.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { isInScope } from "../core/adapter.js";
+import * as kiroProbe from "../probes/kiro.js";
+import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
+import { resolveMcpPlan } from "./mcpPlan.js";
+import { declaredEnvNames } from "../lib/envVarNames.js";
+/** VS-Code-family global settings path. macOS only — see
+ * trellis-kiro-approved-env-vars proposal.md Non-Goals: Linux/Windows
+ * equivalents are the well-known convention but unverified against a
+ * real Kiro install on those platforms. */
+function kiroSettingsPath(homeDir) {
+    return join(homeDir, "Library", "Application Support", "Kiro", "User", "settings.json");
+}
+const APPROVED_ENV_VARS_KEY = "kiroAgent.mcpApprovedEnvVars";
+export class KiroAdapter {
+    homeDir;
+    name = "Kiro";
+    id = "kiro";
+    constructor(homeDir = homedir()) {
+        this.homeDir = homeDir;
+    }
+    async probe() {
+        const snapshot = await kiroProbe.probe(this.homeDir);
+        return { present: snapshot.present, version: snapshot.version };
+    }
+    async plan(canonical) {
+        const canonicalRoot = dirname(canonical.instructionsFile);
+        const skillsRoot = join(this.homeDir, ".kiro", "skills");
+        const desiredSkills = canonical.skills
+            .filter((skill) => isInScope(this.id, skill.scope))
+            .map((skill) => ({ name: skill.name, target: skill.dir }));
+        const skillItems = planSymlinks({
+            rootDir: skillsRoot,
+            desired: desiredSkills,
+            canonicalRoot: join(canonicalRoot, "skills"),
+            kind: "skill",
+        });
+        const instructionsItems = planSymlinks({
+            rootDir: join(this.homeDir, ".kiro", "steering"),
+            desired: [{ name: "CLAUDE.md", target: canonical.instructionsFile }],
+            canonicalRoot,
+            kind: "instructions",
+        });
+        const mcpItems = this.planMcp(canonical);
+        const approvedEnvVarsItems = this.planApprovedEnvVars(canonical);
+        return [...skillItems, ...instructionsItems, ...mcpItems, ...approvedEnvVarsItems];
+    }
+    planMcp(canonical) {
+        const configPath = join(this.homeDir, ".kiro", "settings", "mcp.json");
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id });
+    }
+    /** Names come from `resolveMcpPlan`, not a raw scan of `canonical.mcp.servers`
+     * (design.md D2) — a server scoped away from Kiro, or refused for a
+     * known_host_injected collision, never contributes a name here either. */
+    desiredApprovedEnvVars(canonical) {
+        const { desired } = resolveMcpPlan(this.id, canonical.mcp);
+        const names = new Set();
+        for (const { def } of desired) {
+            for (const name of declaredEnvNames(def))
+                names.add(name);
+        }
+        return [...names];
+    }
+    planApprovedEnvVars(canonical) {
+        const desired = this.desiredApprovedEnvVars(canonical);
+        if (desired.length === 0) {
+            return [];
+        }
+        const settingsPath = kiroSettingsPath(this.homeDir);
+        let existing = [];
+        if (existsSync(settingsPath)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+            }
+            catch {
+                return [{ action: "conflict", kind: "kiro-approved-env-vars", target: settingsPath, description: `${settingsPath} is not valid JSON — refusing to touch it` }];
+            }
+            const current = parsed[APPROVED_ENV_VARS_KEY];
+            if (Array.isArray(current)) {
+                existing = current.filter((v) => typeof v === "string");
+            }
+        }
+        const union = [...new Set([...existing, ...desired])];
+        if (union.length === existing.length && union.every((name) => existing.includes(name))) {
+            return []; // already a superset — no-op (design.md D4)
+        }
+        return [
+            {
+                action: "create",
+                kind: "kiro-approved-env-vars",
+                target: settingsPath,
+                approvedEnvVars: union,
+                description: `${settingsPath}: ${APPROVED_ENV_VARS_KEY} updated to include ${desired.filter((n) => !existing.includes(n)).join(", ")}`,
+            },
+        ];
+    }
+    async apply(plan) {
+        await applySymlinkPlan(plan.filter((item) => item.kind === "skill" || item.kind === "instructions"));
+        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
+        if (mcpCreates.length > 0) {
+            const configPath = mcpCreates[0].target;
+            const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+            const merged = applyJsonMcp(parsed, mcpCreates);
+            mkdirSync(dirname(configPath), { recursive: true });
+            writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+        }
+        const approvedEnvVarsCreate = plan.find((item) => item.kind === "kiro-approved-env-vars" && item.action === "create" && item.approvedEnvVars);
+        if (approvedEnvVarsCreate) {
+            const settingsPath = approvedEnvVarsCreate.target;
+            const parsed = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf-8")) : {};
+            const merged = { ...parsed, [APPROVED_ENV_VARS_KEY]: approvedEnvVarsCreate.approvedEnvVars };
+            mkdirSync(dirname(settingsPath), { recursive: true });
+            writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+        }
+    }
+    async verify(canonical) {
+        const snapshot = await kiroProbe.probe(this.homeDir);
+        if (!snapshot.present) {
+            return { ok: false, mismatches: ["kiro is not present on this machine"] };
+        }
+        const mismatches = [];
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
+        for (const name of desiredNames) {
+            if (!actualSkills.has(name)) {
+                mismatches.push(`skill "${name}" is in canonical scope for kiro but missing on disk`);
+            }
+        }
+        for (const name of actualSkills) {
+            if (!desiredNames.has(name)) {
+                mismatches.push(`skill "${name}" is present on disk but not in canonical scope for kiro`);
+            }
+        }
+        const settingsPath = kiroSettingsPath(this.homeDir);
+        const approved = (() => {
+            if (!existsSync(settingsPath))
+                return [];
+            try {
+                const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+                const current = parsed[APPROVED_ENV_VARS_KEY];
+                return Array.isArray(current) ? current.filter((v) => typeof v === "string") : [];
+            }
+            catch {
+                return [];
+            }
+        })();
+        for (const name of this.desiredApprovedEnvVars(canonical)) {
+            if (!approved.includes(name)) {
+                mismatches.push(`env var "${name}" is needed by a canonical MCP server for kiro but missing from ${APPROVED_ENV_VARS_KEY}`);
+            }
+        }
+        return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+    }
+}

package/dist/adapters/mcpPlan.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Storage-agnostic MCP planning shared by all three adapters (Claude
+ * Code, Codex, Kiro): given canonical MCP config + an agent id, resolves
+ * which (name, def) entries should exist and which are refused
+ * (collision or literal-secret conflicts). Never touches a file itself —
+ * each adapter turns this into plan items using its own read/write
+ * mechanism (JSON merge vs. TOML section splice).
+ *
+ * No automatic removal here (design.md D7, trellis-mcp-sync-p2): unlike a
+ * skill's symlink, a plain key has no ownership marker, so "not in
+ * canonical anymore" can't be distinguished from "the user configured
+ * this directly." Only create/repair + refuse.
+ */
+import type { AgentId, McpConfig, McpServerDef } from "../core/types.js";
+export declare const HUB_ENTRY_NAME = "trellis-hub";
+export interface DesiredMcpEntry {
+    name: string;
+    def: McpServerDef;
+}
+export interface McpConflict {
+    name: string;
+    message: string;
+}
+export interface McpPlanResult {
+    desired: DesiredMcpEntry[];
+    conflicts: McpConflict[];
+}
+export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig): McpPlanResult;

package/dist/adapters/mcpPlan.js

@@ -0,0 +1,83 @@
+/**
+ * Storage-agnostic MCP planning shared by all three adapters (Claude
+ * Code, Codex, Kiro): given canonical MCP config + an agent id, resolves
+ * which (name, def) entries should exist and which are refused
+ * (collision or literal-secret conflicts). Never touches a file itself —
+ * each adapter turns this into plan items using its own read/write
+ * mechanism (JSON merge vs. TOML section splice).
+ *
+ * No automatic removal here (design.md D7, trellis-mcp-sync-p2): unlike a
+ * skill's symlink, a plain key has no ownership marker, so "not in
+ * canonical anymore" can't be distinguished from "the user configured
+ * this directly." Only create/repair + refuse.
+ */
+import { isInScope } from "../core/adapter.js";
+import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
+export const HUB_ENTRY_NAME = "trellis-hub";
+const CODEX_STDIO_URL_CRASH_NOTE = ' On Codex specifically, this crashes the entire process at startup ("url is not supported for stdio"), not just this one server — see docs/research.md.';
+function collisionMessage(name, agentId) {
+    return `refusing to write MCP server "${name}": also appears in known_host_injected.${agentId === "codex" ? CODEX_STDIO_URL_CRASH_NOTE : ""}`;
+}
+/**
+ * Known-dangerous literal patterns (design.md D5) — mirrors
+ * schema/secrets.policy.example.yaml's own examples. A narrow, hardcoded
+ * floor, not the full configurable policy (P3's job).
+ */
+const DANGEROUS_LITERAL_PATTERNS = [
+    { label: "GitLab personal access token (glpat-)", pattern: /glpat-/ },
+    { label: "OpenAI-style secret key (sk-)", pattern: /\bsk-[A-Za-z0-9]/ },
+    { label: "GitHub personal access token (ghp_)", pattern: /ghp_/ },
+    { label: "mcp-router token (mcpr_)", pattern: /mcpr_/ },
+];
+function findLiteralSecret(def) {
+    const candidates = [def.command, def.url, ...(def.args ?? []), ...Object.values(def.headers ?? {})].filter((v) => typeof v === "string");
+    for (const candidate of candidates) {
+        for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
+            if (pattern.test(candidate)) {
+                return label;
+            }
+        }
+    }
+    return undefined;
+}
+export function resolveMcpPlan(agentId, mcp) {
+    if (mcp.hub) {
+        if (mcp.knownHostInjected.includes(HUB_ENTRY_NAME)) {
+            return { desired: [], conflicts: [{ name: HUB_ENTRY_NAME, message: collisionMessage(HUB_ENTRY_NAME, agentId) }] };
+        }
+        return { desired: [{ name: HUB_ENTRY_NAME, def: { transport: "http", url: mcp.hub.url } }], conflicts: [] };
+    }
+    const desired = [];
+    const conflicts = [];
+    for (const [name, def] of Object.entries(mcp.servers)) {
+        if (!isInScope(agentId, def.agents)) {
+            continue;
+        }
+        if (mcp.knownHostInjected.includes(name)) {
+            conflicts.push({ name, message: collisionMessage(name, agentId) });
+            continue;
+        }
+        const secretLabel = findLiteralSecret(def);
+        if (secretLabel) {
+            conflicts.push({
+                name,
+                message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+            });
+            continue;
+        }
+        // Codex has no generic headers concept — only the single
+        // Authorization-bearer-token shape is expressible there
+        // (trellis-mcp-transport-auth design.md D4). Any other shape is
+        // refused for Codex specifically; every other in-scope agent for
+        // the same server is unaffected (this loop runs once per agentId).
+        if (agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
+            conflicts.push({
+                name,
+                message: `refusing to write MCP server "${name}" for codex: its "headers" field isn't the single { Authorization: "Bearer \${VAR}" } shape Codex's own config format can express — Codex has no generic headers concept, only \`bearer_token_env_var\`. Still written normally for every other in-scope agent.`,
+            });
+            continue;
+        }
+        desired.push({ name, def });
+    }
+    return { desired, conflicts };
+}

package/dist/adapters/pi.d.ts

@@ -0,0 +1,23 @@
+/**
+ * pi adapter: `~/.pi/agent/skills/<name>` symlinks, `~/.pi/agent/AGENTS.md`
+ * symlinked to canonical `agents.md` — specifically `AGENTS.md`, not
+ * `AGENTS.override.md` (design.md D3, trellis-sync-p1: pi checks the
+ * override name first, and Trellis's managed file is the baseline, not an
+ * override of something else). pi has no native MCP client (docs/research.md),
+ * so MCP access is delivered as a single symlinked bridge extension
+ * instead of native config (trellis-pi-mcp-bridge-p4) — a different
+ * mechanism from every other agent's config-generation adapter, but the
+ * same symlink create/repair/remove machinery as skills/instructions.
+ */
+import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
+import type { CanonicalSource } from "../core/types.js";
+export declare class PiAdapter implements TrellisAdapter {
+    private readonly homeDir;
+    readonly name = "pi";
+    readonly id: "pi";
+    constructor(homeDir?: string);
+    probe(): Promise<AdapterProbeResult>;
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    apply(plan: AdapterPlanItem[]): Promise<void>;
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}

package/dist/adapters/pi.js

@@ -0,0 +1,108 @@
+/**
+ * pi adapter: `~/.pi/agent/skills/<name>` symlinks, `~/.pi/agent/AGENTS.md`
+ * symlinked to canonical `agents.md` — specifically `AGENTS.md`, not
+ * `AGENTS.override.md` (design.md D3, trellis-sync-p1: pi checks the
+ * override name first, and Trellis's managed file is the baseline, not an
+ * override of something else). pi has no native MCP client (docs/research.md),
+ * so MCP access is delivered as a single symlinked bridge extension
+ * instead of native config (trellis-pi-mcp-bridge-p4) — a different
+ * mechanism from every other agent's config-generation adapter, but the
+ * same symlink create/repair/remove machinery as skills/instructions.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { isInScope } from "../core/adapter.js";
+import * as piProbe from "../probes/pi.js";
+import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+const BRIDGE_SYMLINK_NAME = "trellis-mcp-bridge.js";
+/**
+ * The bundled bridge file's location — always `<repo-root>/dist/pi-bridge/
+ * bundle.js`, never `~/.trellis/` (it's Trellis's own packaged code, not a
+ * user-authored capability — design.md D2). Resolved relative to *this
+ * currently executing module* rather than assumed: both `src/adapters/
+ * pi.ts` (dev, via tsx) and `dist/adapters/pi.js` (published) sit exactly
+ * two directories below the repo root, so `../../dist/pi-bridge/bundle.js`
+ * resolves correctly from either.
+ *
+ * Always the *bundled* output, in dev too — never the raw
+ * `src/pi-bridge/index.ts` source. Node's loader resolves a symlinked
+ * file's own bare-specifier imports relative to the *symlink's path*
+ * (`~/.pi/agent/extensions/...`), not its realpath, so an unbundled file
+ * can never resolve `typebox`/`@modelcontextprotocol/sdk` once symlinked
+ * into an arbitrary user's home directory — confirmed empirically in the
+ * real sandbox (design.md D6). `scripts/build-pi-bridge.mjs` must have run
+ * (part of `npm run build`) before this symlink is of any use to pi.
+ */
+function resolveBridgeFile() {
+    const currentFile = fileURLToPath(import.meta.url);
+    return {
+        file: join(dirname(currentFile), "..", "..", "dist", "pi-bridge", "bundle.js"),
+        symlinkName: BRIDGE_SYMLINK_NAME,
+    };
+}
+export class PiAdapter {
+    homeDir;
+    name = "pi";
+    id = "pi";
+    constructor(homeDir = homedir()) {
+        this.homeDir = homeDir;
+    }
+    async probe() {
+        const snapshot = await piProbe.probe(this.homeDir);
+        return { present: snapshot.present, version: snapshot.version };
+    }
+    async plan(canonical) {
+        const canonicalRoot = dirname(canonical.instructionsFile);
+        const agentDir = join(this.homeDir, ".pi", "agent");
+        const desiredSkills = canonical.skills
+            .filter((skill) => isInScope(this.id, skill.scope))
+            .map((skill) => ({ name: skill.name, target: skill.dir }));
+        const skillItems = planSymlinks({
+            rootDir: join(agentDir, "skills"),
+            desired: desiredSkills,
+            canonicalRoot: join(canonicalRoot, "skills"),
+            kind: "skill",
+        });
+        const instructionsItems = planSymlinks({
+            rootDir: agentDir,
+            desired: [{ name: "AGENTS.md", target: canonical.instructionsFile }],
+            canonicalRoot,
+            kind: "instructions",
+        });
+        const { file: bridgeFile, symlinkName } = resolveBridgeFile();
+        const extensionItems = planSymlinks({
+            rootDir: join(agentDir, "extensions"),
+            desired: [{ name: symlinkName, target: bridgeFile }],
+            // The bridge file's own parent directory, not `~/.trellis/` —
+            // proves ownership for removal against Trellis's own install path
+            // (design.md D2), same role `canonicalRoot` plays for skills.
+            canonicalRoot: dirname(bridgeFile),
+            kind: "extension",
+        });
+        return [...skillItems, ...instructionsItems, ...extensionItems];
+    }
+    async apply(plan) {
+        await applySymlinkPlan(plan);
+    }
+    async verify(canonical) {
+        const snapshot = await piProbe.probe(this.homeDir);
+        if (!snapshot.present) {
+            return { ok: false, mismatches: ["pi is not present on this machine"] };
+        }
+        const mismatches = [];
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
+        for (const name of desiredNames) {
+            if (!actualSkills.has(name)) {
+                mismatches.push(`skill "${name}" is in canonical scope for pi but missing on disk`);
+            }
+        }
+        for (const name of actualSkills) {
+            if (!desiredNames.has(name)) {
+                mismatches.push(`skill "${name}" is present on disk but not in canonical scope for pi`);
+            }
+        }
+        return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+    }
+}

package/dist/adapters/symlinkPlan.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared create/repair/remove/refuse decision logic every adapter needs
+ * for both skills and the instructions file (openspec/changes/
+ * trellis-sync-p1/specs/skill-instructions-sync/spec.md) — built once,
+ * reused by every adapter rather than reimplemented per agent.
+ */
+import type { AdapterPlanItem } from "../core/adapter.js";
+export interface DesiredSymlink {
+    /** Basename this entry should have under `rootDir`. */
+    name: string;
+    /** Absolute path the symlink should point at (inside `canonicalRoot`). */
+    target: string;
+}
+/**
+ * `rootDir` is the directory entries are named directly under (e.g.
+ * `~/.claude/skills`, or the instructions file's own parent directory when
+ * `desired` has exactly one entry). `canonicalRoot` is what proves
+ * ownership for removal — an existing symlink's stored (readlink) target
+ * must resolve inside it before this function will ever plan removing it.
+ * Deliberately not realpath-based here (unlike `isSymlinkTo` above, used
+ * for create/repair): a symlink whose canonical target was just deleted
+ * is broken by construction, and realpath throws on those — exactly the
+ * case this removal path exists to catch.
+ */
+export declare function planSymlinks(opts: {
+    rootDir: string;
+    desired: DesiredSymlink[];
+    canonicalRoot: string;
+    kind: "skill" | "instructions" | "extension";
+}): AdapterPlanItem[];
+/** Executes a `planSymlinks` result. "conflict" is report-only — see
+ * src/core/adapter.ts's `apply()` doc for why this never throws. */
+export declare function applySymlinkPlan(plan: AdapterPlanItem[]): Promise<void>;

package/dist/adapters/symlinkPlan.js

@@ -0,0 +1,120 @@
+/**
+ * Shared create/repair/remove/refuse decision logic every adapter needs
+ * for both skills and the instructions file (openspec/changes/
+ * trellis-sync-p1/specs/skill-instructions-sync/spec.md) — built once,
+ * reused by every adapter rather than reimplemented per agent.
+ */
+import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
+import { mkdir, rm, symlink } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { isSymlinkTo } from "../lib/fsIdentity.js";
+function isUnderRoot(path, root) {
+    const normalizedRoot = resolve(root);
+    const normalizedPath = resolve(path);
+    if (normalizedPath === normalizedRoot)
+        return true;
+    const prefix = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
+    return normalizedPath.startsWith(prefix);
+}
+/**
+ * `rootDir` is the directory entries are named directly under (e.g.
+ * `~/.claude/skills`, or the instructions file's own parent directory when
+ * `desired` has exactly one entry). `canonicalRoot` is what proves
+ * ownership for removal — an existing symlink's stored (readlink) target
+ * must resolve inside it before this function will ever plan removing it.
+ * Deliberately not realpath-based here (unlike `isSymlinkTo` above, used
+ * for create/repair): a symlink whose canonical target was just deleted
+ * is broken by construction, and realpath throws on those — exactly the
+ * case this removal path exists to catch.
+ */
+export function planSymlinks(opts) {
+    const { rootDir, desired, kind } = opts;
+    const items = [];
+    const desiredNames = new Set(desired.map((d) => d.name));
+    const canonicalRootResolved = resolve(opts.canonicalRoot);
+    for (const { name, target } of desired) {
+        const path = join(rootDir, name);
+        if (isSymlinkTo(path, target)) {
+            continue; // already correct — no-op
+        }
+        if (existsSync(path) && !lstatSync(path).isSymbolicLink()) {
+            items.push({
+                action: "conflict",
+                kind,
+                target: path,
+                description: `${path} exists and is not a Trellis-managed symlink — left untouched`,
+            });
+            continue;
+        }
+        items.push({
+            action: "create",
+            kind,
+            target: path,
+            linkTarget: target,
+            description: `symlink ${path} -> ${target}`,
+        });
+    }
+    let existingEntries = [];
+    try {
+        existingEntries = readdirSync(rootDir);
+    }
+    catch {
+        existingEntries = [];
+    }
+    for (const name of existingEntries) {
+        if (desiredNames.has(name))
+            continue;
+        const path = join(rootDir, name);
+        let isSymlink;
+        try {
+            isSymlink = lstatSync(path).isSymbolicLink();
+        }
+        catch {
+            continue;
+        }
+        if (!isSymlink)
+            continue; // real content, not Trellis's — never touched, never even reported
+        // Ownership proof uses the symlink's raw stored target (readlink), not
+        // realpath: the whole point of this branch is deleted-canonical-entry
+        // symlinks, which are BROKEN by construction (their target no longer
+        // exists) — realpath throws on those, which would silently skip
+        // exactly the case "remove a deleted skill's stale symlink" exists to
+        // catch. Trellis always writes an absolute path as the link target
+        // (see applySymlinkPlan), so comparing the raw stored string against
+        // canonicalRoot needs no filesystem resolution on either side.
+        let linkTarget;
+        try {
+            linkTarget = readlinkSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!isUnderRoot(linkTarget, canonicalRootResolved))
+            continue; // points somewhere else — not ours
+        items.push({
+            action: "remove",
+            kind,
+            target: path,
+            description: `remove stale symlink ${path} (canonical entry gone or scoped away)`,
+        });
+    }
+    return items;
+}
+/** Executes a `planSymlinks` result. "conflict" is report-only — see
+ * src/core/adapter.ts's `apply()` doc for why this never throws. */
+export async function applySymlinkPlan(plan) {
+    for (const item of plan) {
+        if (item.action === "conflict")
+            continue;
+        if (item.action === "remove") {
+            await rm(item.target, { force: true });
+            continue;
+        }
+        // "create": rootDir may not exist yet (first sync ever for this agent)
+        if (!item.linkTarget)
+            continue;
+        await mkdir(resolve(item.target, ".."), { recursive: true });
+        await rm(item.target, { force: true }); // clear a wrong-target symlink before repointing
+        await symlink(item.linkTarget, item.target);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Entry point. Stays a thin dispatcher; real logic lives in
+ * src/commands/*.ts so it stays testable without going through argv. See
+ * docs/roadmap.md for what's implemented.
+ */
+export {};