docks-kit 0.15.1 → 0.15.2

package/cli/src/engine-native/index.ts

@@ -17,12 +17,15 @@ import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } f
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { normalizeManifest, skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+import { ExitError, parseArgs, parseClaudePlugin, parseCompactWindow, validateModifierFlags } from "./parseArgs"
 
 export type ModifierFlag =
   | "--claude-model"
   | "--claude-effort"
   | "--claude-advisor"
+  | "--claude-compact-window"
+  | "--claude-permissive"
+  | "--claude-plugin"
   | "--codex-model"
   | "--codex-effort"
 
@@ -117,6 +120,16 @@ export interface Ctx {
 function makeCtx(services: EngineServices): Ctx {
   const env = process.env
   const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir()
+  const compactWindowSource = env["CLAUDE_COMPACT_WINDOW"] ?? ""
+  const claudeCompactWindow = compactWindowSource === "" ? "" : parseCompactWindow(compactWindowSource)
+  if (claudeCompactWindow === undefined) {
+    services.logger.err("CLAUDE_COMPACT_WINDOW expects a token count (e.g. 680000 or 680k)")
+    throw new ExitError(2)
+  }
+  const claudePlugins = (env["CLAUDE_PLUGINS"] ?? "")
+    .split(" ")
+    .filter((plugin) => plugin !== "")
+    .map((plugin) => parseClaudePlugin(plugin, services.logger.err))
   return {
     repoDir: kitHome(),
     home,
@@ -128,9 +141,9 @@ function makeCtx(services: EngineServices): Ctx {
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
     assumeYes: env["ASSUME_YES"] === "1",
-    claudeCompactWindow: env["CLAUDE_COMPACT_WINDOW"] ?? "",
+    claudeCompactWindow,
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
-    claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
+    claudePlugins,
     claudeModel: env["CLAUDE_MODEL"] ?? "",
     claudeEffort: "",
     claudeAdvisor: "",
@@ -278,8 +291,8 @@ export async function runEngineNative(argv: ReadonlyArray<string>, services?: En
     deps: baseServices.deps,
     platform: baseServices.platform
   }
-  ctx = makeCtx(runServices)
   try {
+    ctx = makeCtx(runServices)
     switch (argv[0]) {
       case "model":
         return modeModel(ctx, argv.slice(1))

package/cli/src/engine-native/models.ts

@@ -6,16 +6,9 @@ import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { payloadDisplayPath, payloadText } from "../payload"
 
-function catalog(): Json | undefined {
-  try {
-    return parseJson(payloadText("SoT/models.json"))
-  } catch {
-    return undefined
-  }
-}
 
 function toolEntry(tool: string): { [k: string]: Json } | undefined {
-  const doc = catalog()
+  const doc = parseJson(payloadText("SoT/models.json"))
   if (doc === undefined || !isObject(doc)) return undefined
   const entry = doc[tool]
   return entry !== undefined && isObject(entry) ? entry : undefined
@@ -37,7 +30,7 @@ export function printModels(ctx: Ctx, tool: string): void {
   const { echo, warn } = ctx.services.logger
   const entry = toolEntry(tool)
   if (entry === undefined) {
-    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json", ctx.repoDir)})`)
+    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json")})`)
     return
   }
   const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?"

package/cli/src/engine-native/modes.ts

@@ -37,19 +37,29 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   if (value === "") {
     if (tool === "claude") {
       const deployed = p(ctx.home, ".claude", "settings.json")
-      if (!fileReadable(deployed)) {
+      const result = readConfig(deployed)
+      if (result.kind === "missing") {
         warn("~/.claude/settings.json missing")
         return 0
       }
-      echo(`deployed: ${jsonModelField(deployed)}`)
+      if (result.kind === "read-error") {
+        err(`Failed to read ~/.claude/settings.json: ${String(result.error)}`)
+        return 1
+      }
+      echo(`deployed: ${jsonModelText(result.data)}`)
       echo(`SoT:      ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`)
     } else {
       const deployed = p(ctx.home, ".codex", "config.toml")
-      if (!fileReadable(deployed)) {
+      const result = readConfig(deployed)
+      if (result.kind === "missing") {
         warn("~/.codex/config.toml missing")
         return 0
       }
-      echo(`deployed: ${tomlModelField(deployed)}`)
+      if (result.kind === "read-error") {
+        err(`Failed to read ~/.codex/config.toml: ${String(result.error)}`)
+        return 1
+      }
+      echo(`deployed: ${tomlModelText(result.data)}`)
       echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`)
     }
     printModels(ctx, tool)
@@ -74,20 +84,23 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   return 0
 }
 
-function fileReadable(p: string): boolean {
+type ConfigReadResult =
+  | { readonly kind: "missing" }
+  | { readonly kind: "read-error"; readonly error: unknown }
+  | { readonly kind: "data"; readonly data: string }
+
+function readConfig(file: string): ConfigReadResult {
   try {
-    readFileSync(p)
-    return true
-  } catch {
-    return false
+    return { kind: "data", data: readFileSync(file, "utf8") }
+  } catch (error) {
+    const code =
+      typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : undefined
+    return code === "ENOENT" ? { kind: "missing" } : { kind: "read-error", error }
   }
 }
 
-/** `jq -r '.model // "default (unset)"'` — empty on unparseable input. */
-function jsonModelField(file: string): string {
-  return jsonModelText(readFileSync(file, "utf8"))
-}
-
 function jsonModelText(text: string): string {
   const doc = parseJson(text)
   if (doc === undefined) return ""
@@ -97,9 +110,6 @@ function jsonModelText(text: string): string {
 }
 
 /** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
-function tomlModelField(file: string): string {
-  return tomlModelText(readFileSync(file, "utf8"))
-}
 
 function tomlModelText(text: string): string {
   for (const line of text.split("\n")) {
@@ -110,9 +120,9 @@ function tomlModelText(text: string): string {
 
 export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
   const { err } = ctx.services.logger
-  const words = args.filter((a) => !a.startsWith("--"))
-  const op = words[0] ?? args[0] ?? "check"
-  const tool = words[1] ?? args[1] ?? ""
+  const words = args.filter((arg) => !arg.startsWith("--"))
+  const op = words[0] ?? "check"
+  const tool = words[1] ?? ""
   for (const arg of args) {
     if (arg === "--yes") ctx.assumeYes = true
     else if (arg === "--verbose") {
@@ -128,7 +138,7 @@ export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Prom
     err("Usage: toolchain [check|ensure <tool>] [--yes]")
     return 2
   }
-  if (tool === "" || tool === "--yes") {
+  if (tool === "") {
     err("Usage: toolchain ensure <tool> [--yes]")
     return 2
   }

package/cli/src/engine-native/os.ts

@@ -14,11 +14,3 @@ export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName
   return pf === "linux" ? "linux" : pf === "darwin" ? "darwin" : "unknown"
 }
 
-export function isLinux(): boolean {
-  return rawPlatform() === "linux"
-}
-
-/** Shell-rc exports apply only on supported hosts. */
-export function shellRcApplicable(): boolean {
-  return platformName() !== "unknown"
-}

package/cli/src/engine-native/parseArgs.ts

@@ -24,13 +24,96 @@ export class ExitError extends Error {
 }
 
 export const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
-const MODIFIER_FLAGS = new Set<ModifierFlag>([
-  "--claude-model",
-  "--claude-effort",
-  "--claude-advisor",
-  "--codex-model",
-  "--codex-effort"
-])
+
+interface ModifierMetadata {
+  readonly target: "claude" | "codex"
+  readonly ignoredWarning: string
+  readonly hasValue: (ctx: Ctx) => boolean
+  readonly clear: (ctx: Ctx) => void
+}
+
+const MODIFIER_METADATA = {
+  "--claude-model": {
+    target: "claude",
+    ignoredWarning: "--claude-model ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeModel !== "",
+    clear: (ctx) => {
+      ctx.claudeModel = ""
+    }
+  },
+  "--claude-effort": {
+    target: "claude",
+    ignoredWarning: "--claude-effort ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeEffort !== "",
+    clear: (ctx) => {
+      ctx.claudeEffort = ""
+    }
+  },
+  "--claude-advisor": {
+    target: "claude",
+    ignoredWarning: "--claude-advisor ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeAdvisor !== "",
+    clear: (ctx) => {
+      ctx.claudeAdvisor = ""
+    }
+  },
+  "--claude-compact-window": {
+    target: "claude",
+    ignoredWarning: "--claude-compact-window ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeCompactWindow !== "",
+    clear: (ctx) => {
+      ctx.claudeCompactWindow = ""
+    }
+  },
+  "--claude-permissive": {
+    target: "claude",
+    ignoredWarning: "--claude-permissive ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudePermissive,
+    clear: (ctx) => {
+      ctx.claudePermissive = false
+    }
+  },
+  "--claude-plugin": {
+    target: "claude",
+    ignoredWarning: "--claude-plugin ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudePlugins.length > 0,
+    clear: (ctx) => {
+      ctx.claudePlugins = []
+    }
+  },
+  "--codex-model": {
+    target: "codex",
+    ignoredWarning: "--codex-model ignored: codex target not selected",
+    hasValue: (ctx) => ctx.codexModel !== "",
+    clear: (ctx) => {
+      ctx.codexModel = ""
+    }
+  },
+  "--codex-effort": {
+    target: "codex",
+    ignoredWarning: "--codex-effort ignored: codex target not selected",
+    hasValue: (ctx) => ctx.codexEffort !== "",
+    clear: (ctx) => {
+      ctx.codexEffort = ""
+    }
+  }
+} satisfies Record<ModifierFlag, ModifierMetadata>
+
+type ScalarModifierFlag =
+  | "--claude-model"
+  | "--claude-effort"
+  | "--claude-advisor"
+  | "--codex-model"
+  | "--codex-effort"
+
+const SCALAR_MODIFIER_FLAGS: Record<ScalarModifierFlag, true> = {
+  "--claude-model": true,
+  "--claude-effort": true,
+  "--claude-advisor": true,
+  "--codex-model": true,
+  "--codex-effort": true
+}
+
 
 function usage(ctx: Ctx): void {
   const { echo } = ctx.services.logger
@@ -86,13 +169,33 @@ export function parseCompactWindow(v: string): string | undefined {
   return /^[0-9]+$/.test(v) ? v : undefined
 }
 
-function addClaudePlugin(ctx: Ctx, name: string): void {
-  const { err } = ctx.services.logger
+export function parseClaudePlugin(name: string, err: (message: string) => void): string {
   if (!KNOWN_CLAUDE_OPTIN_PLUGINS.includes(name)) {
     err(`Unknown opt-in plugin '${name}'. Known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}`)
     throw new ExitError(2)
   }
-  ctx.claudePlugins.push(name)
+  return name
+}
+
+function markModifier(ctx: Ctx, flag: ModifierFlag): void {
+  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
+  flags.add(flag)
+  ctx.modifierFlags = flags
+}
+
+function addClaudePlugin(ctx: Ctx, name: string): void {
+  if (name === "") {
+    printCatalog(
+      ctx,
+      `Available Claude optional plugins:\n${KNOWN_CLAUDE_OPTIN_PLUGINS.map((plugin) => `  ${plugin}`).join("\n")}`
+    )
+    ctx.services.logger.err(
+      `Invalid Claude plugin '' — valid: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}`
+    )
+    throw new ExitError(2)
+  }
+  ctx.claudePlugins.push(parseClaudePlugin(name, ctx.services.logger.err))
+  markModifier(ctx, "--claude-plugin")
 }
 
 function selectTarget(ctx: Ctx, target: string): void {
@@ -102,7 +205,7 @@ function selectTarget(ctx: Ctx, target: string): void {
   ctx.targetFilterSet = true
 }
 
-function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
+function setModifier(ctx: Ctx, flag: ScalarModifierFlag, value: string): void {
   switch (flag) {
     case "--claude-model":
       ctx.claudeModel = value
@@ -120,20 +223,19 @@ function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
       ctx.codexEffort = value
       break
   }
-  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
-  flags.add(flag)
-  ctx.modifierFlags = flags
+  markModifier(ctx, flag)
 }
 
-function isModifierFlag(value: string): value is ModifierFlag {
-  return MODIFIER_FLAGS.has(value as ModifierFlag)
+function isScalarModifierFlag(value: string): value is ScalarModifierFlag {
+  return SCALAR_MODIFIER_FLAGS[value as ScalarModifierFlag] === true
 }
 
+
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   const { err } = ctx.services.logger
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index] ?? ""
-    if (isModifierFlag(arg) && args[index + 1] === "") {
+    if (isScalarModifierFlag(arg) && args[index + 1] === "") {
       setModifier(ctx, arg, "")
       index += 1
       continue
@@ -190,6 +292,7 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         throw new ExitError(2)
       case "--claude-permissive":
         ctx.claudePermissive = true
+        markModifier(ctx, "--claude-permissive")
         continue
       case "--claude-plugin":
         err(`--claude-plugin requires a value: --claude-plugin=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`)
@@ -244,8 +347,12 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         throw new ExitError(2)
       }
       ctx.claudeCompactWindow = parsed
+      markModifier(ctx, "--claude-compact-window")
     } else if (arg.startsWith("--claude-plugin=")) {
       addClaudePlugin(ctx, arg.slice("--claude-plugin=".length))
+    } else if (arg.startsWith("--claude-permissive=")) {
+      err("--claude-permissive does not take a value")
+      throw new ExitError(2)
     } else {
       err(`Unknown arg: ${arg}`)
       throw new ExitError(2)
@@ -266,53 +373,49 @@ function printCatalog(ctx: Ctx, catalog: string): void {
 
 export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
-  const supplied = (flag: ModifierFlag, value: string): boolean =>
-    value !== "" || ctx.modifierFlags?.has(flag) === true
-  if (supplied("--claude-model", ctx.claudeModel)) {
-    if (!ctx.syncClaude) {
-      warn("--claude-model ignored: claude target not selected")
-      ctx.claudeModel = ""
-    } else if (!validateClaudeModel(ctx, ctx.claudeModel)) {
+  const supplied = (flag: ModifierFlag): boolean =>
+    MODIFIER_METADATA[flag].hasValue(ctx) || ctx.modifierFlags?.has(flag) === true
+
+  for (const flag of Object.keys(MODIFIER_METADATA) as Array<ModifierFlag>) {
+    const metadata = MODIFIER_METADATA[flag]
+    const targetSelected = metadata.target === "claude" ? ctx.syncClaude : ctx.syncCodex
+    if (!targetSelected && supplied(flag)) {
+      warn(metadata.ignoredWarning)
+      metadata.clear(ctx)
+      ctx.modifierFlags?.delete(flag)
+    }
+  }
+
+  if (supplied("--claude-model")) {
+    if (!validateClaudeModel(ctx, ctx.claudeModel)) {
       printModels(ctx, "claude")
       err(`Invalid Claude model '${ctx.claudeModel}' — use an alias above or a full claude-* ID`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--claude-effort", ctx.claudeEffort)) {
-    if (!ctx.syncClaude) {
-      warn("--claude-effort ignored: claude target not selected")
-      ctx.claudeEffort = ""
-    } else if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
+  if (supplied("--claude-effort")) {
+    if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
       printCatalog(ctx, effortCatalog("claude"))
       err(`Invalid Claude effort '${ctx.claudeEffort}' — valid: ${effortValueGrammar("claude")}`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--claude-advisor", ctx.claudeAdvisor)) {
-    if (!ctx.syncClaude) {
-      warn("--claude-advisor ignored: claude target not selected")
-      ctx.claudeAdvisor = ""
-    } else if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
+  if (supplied("--claude-advisor")) {
+    if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
       printCatalog(ctx, advisorCatalog())
       err(`Invalid Claude advisor state '${ctx.claudeAdvisor}' — valid: ${advisorValueGrammar()}`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--codex-model", ctx.codexModel)) {
-    if (!ctx.syncCodex) {
-      warn("--codex-model ignored: codex target not selected")
-      ctx.codexModel = ""
-    } else if (!validateCodexModel(ctx, ctx.codexModel)) {
+  if (supplied("--codex-model")) {
+    if (!validateCodexModel(ctx, ctx.codexModel)) {
       printModels(ctx, "codex")
       err(`Invalid Codex model '${ctx.codexModel}' — must match ^[A-Za-z0-9._-]+$`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--codex-effort", ctx.codexEffort)) {
-    if (!ctx.syncCodex) {
-      warn("--codex-effort ignored: codex target not selected")
-      ctx.codexEffort = ""
-    } else if (!isEffortModifierValue("codex", ctx.codexEffort)) {
+  if (supplied("--codex-effort")) {
+    if (!isEffortModifierValue("codex", ctx.codexEffort)) {
       printCatalog(ctx, effortCatalog("codex"))
       err(`Invalid Codex effort '${ctx.codexEffort}' — valid: ${effortValueGrammar("codex")}`)
       throw new ExitError(2)

package/cli/src/engine-native/services.ts

@@ -36,8 +36,6 @@ export interface DependencyManager {
 export interface Platform {
   readonly raw: () => NodeJS.Platform
   readonly name: () => PlatformName
-  readonly isLinux: () => boolean
-  readonly shellRcApplicable: () => boolean
 }
 
 export interface EngineServices {
@@ -53,9 +51,7 @@ export interface EngineServiceOptions {
 /** Platform view over an injectable platform id. */
 export const makePlatform = (pf: NodeJS.Platform = rawPlatform()): Platform => ({
   raw: () => pf,
-  name: () => platformName(pf),
-  isLinux: () => pf === "linux",
-  shellRcApplicable: () => pf === "linux" || pf === "darwin"
+  name: () => platformName(pf)
 })
 
 /** DependencyManager whose hints default to the INJECTED platform, not the host. */

package/cli/src/engine-native/settings.ts

@@ -16,8 +16,9 @@ export function reconcileSettings(repo: Json, user: Json): Json {
  * `unique` — i.e. codepoint-sorted and deduplicated, matching jq).
  */
 export function mergeSettings(repo: Json, user: Json): Json {
-  const merged = deepMerge(user, repo)
-  if (!isObject(merged)) return merged
+  const candidate = deepMerge(user, repo)
+  if (!isObject(candidate)) return candidate
+  const merged = { ...candidate }
   const permissions = isObject(merged["permissions"]) ? merged["permissions"] : {}
   merged["permissions"] = {
     ...permissions,

package/cli/src/engine-native/skillsSync.ts

@@ -4,14 +4,16 @@
  * the kit-managed snapshot, the effect-solutions toolchain callback, and the
  * snapshot write.
  */
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs"
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs"
+import { dirname, relative, resolve } from "node:path"
 import { p, spawnProcess, writeFileIfChanged } from "./exec"
 import { bunBootstrap } from "./bun"
 import type { Ctx } from "./index"
-import { compareCodepoints } from "./jq"
+import { compareCodepoints, isObject, parseJson } from "./jq"
 import type { EngineServices } from "./services"
 import { ensure, field } from "./toolchain"
 import { payloadText } from "../payload"
+import { ExitError } from "./parseArgs"
 
 export interface SkillsState {
   present: number
@@ -26,16 +28,18 @@ export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
   if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true })
 
   await syncUniversal(ctx, state, skillsDir, manifest)
-  if (ctx.prune) await reconcileRemovals(ctx, manifest, snapshot)
+  const failedRemovals = ctx.prune ? await reconcileRemovals(ctx, manifest, snapshot) : []
   await syncEffectSolutionsCli(ctx)
-  updateSnapshot(ctx, manifest, snapshot)
+  updateSnapshot(ctx, manifest, snapshot, failedRemovals)
   return state
 }
 
 /** skills::_skills_cli — the pinned npx package spec. */
 function skillsCli(ctx: Ctx): string {
-  const v = field(ctx, "skills-cli", "verified")
-  return v !== "" ? `skills@${v}` : "skills"
+  const version = field(ctx, "skills-cli", "verified")
+  if (version !== "") return `skills@${version}`
+  ctx.services.logger.err("Universal skills sync aborted because SoT/toolchain.json has no verified skills-cli pin")
+  throw new ExitError(1)
 }
 
 /** skills::_normalize_manifest — cleaned slugs, one per line. */
@@ -131,7 +135,7 @@ function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
   const canonical = p(skillsDir, base)
   const claudeSkillsDir = p(ctx.home, ".claude", "skills")
   const claudeLink = p(claudeSkillsDir, base)
-  const relTarget = `../../.agents/skills/${base}`
+  const relTarget = relative(dirname(claudeLink), canonical)
 
   if (!isDir(canonical)) return false
 
@@ -186,31 +190,23 @@ function removeLink(path: string): boolean {
   }
 }
 
-/** skills::_link_or_copy — real symlink preferred, copy fallback. */
+/** skills::_link_or_copy — create a symlink without replacing its source. */
 export function linkOrCopy(target: string, link: string): boolean {
+  const resolvedLink = resolve(link)
+  if (resolve(dirname(resolvedLink), target) === resolvedLink) return true
   removeLink(link)
   try {
     symlinkSync(target, link)
   } catch {
-    // fall through to the copy fallback below
-  }
-  if (lstat(link)?.isSymbolicLink() === true) return true
-  try {
-    // Resolve a relative target against the link's parent, like ln does.
-    const resolved = target.startsWith("/") ? target : p(link.slice(0, link.lastIndexOf("/")), target)
-    cpSync(resolved, link, { recursive: true })
-  } catch {
-    // fall through to the existence check below
+    return false
   }
-  return existsSync(link)
+  return lstat(link)?.isSymbolicLink() === true
 }
 
 function linkOrCopyWithWarnings(target: string, link: string, services: EngineServices): boolean {
   const linked = linkOrCopy(target, link)
   if (!linked) {
-    services.logger.warn(`could not create ${link} (symlink and copy both failed)`)
-  } else if (lstat(link)?.isSymbolicLink() !== true) {
-    services.logger.warn(`symlinks unsupported here — ${link} is a copy refreshed on sync`)
+    services.logger.warn(`could not create symlink ${link}`)
   }
   return linked
 }
@@ -255,7 +251,10 @@ export function effectSolutionsInstall(
 
 async function syncEffectSolutionsCli(ctx: Ctx): Promise<void> {
   const { clearProgress, progress, warn } = ctx.services.logger
-  if (!/"effect-kit@docks"[ \t]*:[ \t]*true/.test(payloadText("SoT/.claude/settings.json"))) return
+  const settings = parseJson(payloadText("SoT/.claude/settings.json"))
+  if (settings === undefined || !isObject(settings)) return
+  const enabledPlugins = settings["enabledPlugins"]
+  if (enabledPlugins === undefined || !isObject(enabledPlugins) || enabledPlugins["effect-kit@docks"] !== true) return
 
   progress("Checking effect-solutions CLI...")
   const result = await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
@@ -267,7 +266,7 @@ async function syncEffectSolutionsCli(ctx: Ctx): Promise<void> {
 
 // ----------------------------------------------------- prune + snapshot ----
 
-async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Promise<void> {
+async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Promise<Array<string>> {
   const { change, clearProgress, echo, progress, warn } = ctx.services.logger
   if (!existsSync(snapshot)) {
     if (ctx.dryRun) {
@@ -275,15 +274,18 @@ async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
         `[dry-run] (--prune) no kit-managed-skills snapshot yet; first real sync writes ${snapshot}, then future --prune runs reconcile against it`
       )
     }
-    return
+    return []
   }
 
   const current = normalizeManifest(manifest)
+  const currentBases = new Set(current.map((slug) => slug.slice(slug.lastIndexOf("/") + 1)))
   let removed = 0
   let failed = 0
+  const failedSlugs: Array<string> = []
   for (const slug of readSlugs(snapshot)) {
     if (current.includes(slug)) continue
     const base = slug.slice(slug.lastIndexOf("/") + 1)
+    if (currentBases.has(base)) continue
     if (ctx.dryRun) {
       echo(`[dry-run] kit-managed skill no longer in SoT — would remove: ${base}`)
       continue
@@ -298,6 +300,7 @@ async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
     } else {
       warn(`Failed to remove kit-managed skill: ${base}`)
       failed++
+      failedSlugs.push(slug)
     }
   }
 
@@ -306,13 +309,14 @@ async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
     ctx.nextStepTriggers.skillsRestart = true
   }
   if (failed > 0) warn(`${failed} skill remove(s) failed — re-run with --prune or run: npx skills remove --global <name> -y`)
+  return failedSlugs
 }
 
-function updateSnapshot(ctx: Ctx, manifest: string, snapshot: string): void {
+function updateSnapshot(ctx: Ctx, manifest: string, snapshot: string, failedRemovals: ReadonlyArray<string>): void {
   if (ctx.dryRun) return
 
   mkdirSync(ctx.agentsDir, { recursive: true })
-  const sorted = [...new Set(normalizeManifest(manifest))].sort(compareCodepoints)
+  const sorted = [...new Set([...normalizeManifest(manifest), ...failedRemovals])].sort(compareCodepoints)
   writeFileIfChanged(snapshot, sorted.length > 0 ? `${sorted.join("\n")}\n` : "")
 }