docks-kit 0.15.1 → 0.15.2

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

@@ -155,25 +155,29 @@ export async function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): Prom
 
   if (!present(ctx, tool)) {
     const latest = await latestVersion(ctx, tool)
-    if (ctx.dryRun) {
-      echo(`[dry-run] would install ${tool} (${latest !== "" ? latest : "latest"}, gated by toolchain.json verified pin)`)
-      return 0
-    }
     let target: string
     if (latest === "") {
-      target = field(ctx, tool, "verified")
-      if (target !== "" && field(ctx, tool, "pinnable") === "true") {
-        warn(`${tool} latest version unknown (offline?) — installing kit-verified ${target} instead`)
-      } else {
-        target = ""
-        warn(`${tool} latest version unknown (offline?) and not pinnable — installing latest unverified`)
+      const verified = field(ctx, tool, "verified")
+      if (verified === "" || field(ctx, tool, "pinnable") !== "true") {
+        warn(`${tool} install skipped — latest version is unknown and no kit-verified pinnable version is available`)
+        return 0
       }
+      target = verified
+      if (ctx.dryRun) {
+        echo(`[dry-run] would install ${tool} (${target}, kit-verified fallback because latest is unknown)`)
+        return 0
+      }
+      warn(`${tool} latest version unknown (offline?) — installing kit-verified ${target} instead`)
     } else {
+      if (ctx.dryRun) {
+        echo(`[dry-run] would install ${tool} (${latest}, gated by toolchain.json verified pin)`)
+        return 0
+      }
       const g = await gate(ctx, tool, "install", latest)
       if (!g.proceed) return 0
-      target = g.target
+      target = g.target !== "" ? g.target : latest
     }
-    return await installFn("install", target !== "" ? target : latest, ctx.services)
+    return await installFn("install", target, ctx.services)
   }
 
   const installed = await installedVersion(ctx, tool)
@@ -242,7 +246,7 @@ export async function report(ctx: Ctx): Promise<void> {
     const toolId = tool as ToolId
     if (present(ctx, toolId)) {
       installed = await installedVersion(ctx, toolId)
-      status = "ok"
+      status = installed === "" ? "unknown" : "ok"
       if (floor !== "" && installed !== "" && isNewer(floor, installed)) {
         status = "below-floor"
       } else if (verified !== "" && installed !== "" && isNewer(installed, verified)) {

package/cli/src/engine.ts

@@ -1,6 +1,8 @@
+import { CliError } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
 import { spawnSync } from "node:child_process"
 import { runEngineNative } from "./engine-native"
+import { ExitError } from "./engine-native/parseArgs"
 import { makeEngineServices } from "./engine-native/services"
 import { kitHome } from "./kitHome"
 import { DependencyManagerService, LoggerService, PlatformService } from "./services"
@@ -28,6 +30,19 @@ const requireSupportedHost = () => {
 export const compiled =
   process.argv[1] !== undefined && process.argv[1].startsWith("/$bunfs/")
 
+export class EngineCaptureError extends ExitError {
+  constructor(readonly diagnostic: string, code: number) {
+    super(code)
+    this.name = "EngineCaptureError"
+    this.message = diagnostic
+  }
+}
+
+const failureMessage = (error: unknown): string => {
+  if (error instanceof Error && error.message !== "") return error.message
+  return typeof error === "string" && error !== "" ? error : "unknown error"
+}
+
 export const engine = (args: ReadonlyArray<string>) =>
   Effect.gen(function* () {
     yield* requireSupportedHost()
@@ -37,7 +52,13 @@ export const engine = (args: ReadonlyArray<string>) =>
     const logger = yield* LoggerService
     const deps = yield* DependencyManagerService
     const platform = yield* PlatformService
-    const code = yield* Effect.promise(() => runEngineNative(args, { logger, deps, platform }))
+    const code = yield* Effect.tryPromise({
+      try: () => runEngineNative(args, { logger, deps, platform }),
+      catch: (error) => new CliError.UserError({
+        cause: error,
+        userMessage: `engine operation '${args.join(" ") || "default"}' failed: ${failureMessage(error)}`
+      })
+    })
     if (code !== 0) {
       yield* Effect.sync(() => process.exit(code))
     }
@@ -50,19 +71,27 @@ export const engineCapture = (args: ReadonlyArray<string>) =>
     if (bashEngineRequested()) {
       return yield* bail(bashRemovedMessage, 2)
     }
-    return yield* Effect.sync(() => {
+    const res = yield* Effect.sync(() =>
       // Child process (raw channel): runEngineNative writes straight to
-      // process.stdout, so in-process capture isn't possible.
-      const res = spawnSync(process.execPath, compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args], {
+      // process.stdout, so in-process capture is not possible.
+      spawnSync(process.execPath, compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args], {
         env: { ...process.env, DOCKS_KIT_ENGINE: "native-raw" },
         encoding: "utf8",
         stdio: ["ignore", "pipe", "inherit"]
       })
-      if (res.error !== undefined || res.status !== 0) {
-        makeEngineServices().logger.warn(`engine capture failed (${args.join(" ")} exited ${res.status ?? "spawn-error"})`)
-      }
-      return res.stdout ?? ""
-    })
+    )
+    if (res.error !== undefined || res.status !== 0) {
+      const reasons = new Array<string>()
+      if (typeof res.status === "number") reasons.push(`exit ${res.status}`)
+      if (res.signal !== null) reasons.push(`signal ${res.signal}`)
+      if (res.error !== undefined) reasons.push(`spawn error: ${res.error.message}`)
+      if (reasons.length === 0) reasons.push("no child status")
+      const diagnostic = `engine capture failed for '${args.join(" ") || "default"}': ${reasons.join("; ")}`
+      makeEngineServices().logger.err(diagnostic)
+      const code = typeof res.status === "number" && res.status !== 0 ? res.status : 1
+      return yield* Effect.fail(new EngineCaptureError(diagnostic, code))
+    }
+    return res.stdout ?? ""
   })
 
 /** Print a message to stderr and exit — for CLI-side validation failures. */

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.15.1"
+export const GENERATED_PACKAGE_VERSION = "0.15.2"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",
@@ -12,7 +12,7 @@ export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.claude/settings.json": "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"minimumVersion\": \"2.1.219\",\n  \"model\": \"opus\",\n  \"effortLevel\": \"high\",\n  \"autoMemoryEnabled\": true,\n  \"skillListingMaxDescChars\": 2048,\n  \"respectGitignore\": true,\n  \"cleanupPeriodDays\": 14,\n  \"skillListingBudgetFraction\": 0.05,\n  \"env\": {\n    \"CLAUDE_CODE_MAX_OUTPUT_TOKENS\": \"64000\",\n    \"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR\": \"1\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"468000\",\n    \"CLAUDE_CODE_NO_FLICKER\": \"1\"\n  },\n  \"permissions\": {\n    \"defaultMode\": \"auto\",\n    \"allow\": [\n      \"Read\",\n      \"Glob\",\n      \"Grep\",\n      \"WebFetch\",\n      \"WebSearch\",\n      \"Edit(./)\",\n      \"Bash(git *)\",\n      \"Bash(git add *)\",\n      \"Bash(git commit *)\",\n      \"Bash(git status *)\",\n      \"Bash(git diff *)\",\n      \"Bash(git log *)\",\n      \"Bash(git branch *)\",\n      \"Bash(git checkout *)\",\n      \"Bash(git switch *)\",\n      \"Bash(git stash *)\",\n      \"Bash(git fetch *)\",\n      \"Bash(git pull *)\",\n      \"Bash(git tag *)\",\n      \"Bash(git show *)\",\n      \"Bash(git blame *)\",\n      \"Bash(git worktree *)\",\n      \"Bash(gh *)\",\n      \"Bash(pnpm *)\",\n      \"Bash(npm *)\",\n      \"Bash(npx *)\",\n      \"Bash(node *)\",\n      \"Bash(docker *)\",\n      \"Bash(docker-compose *)\",\n      \"Bash(ls *)\",\n      \"Bash(cat *)\",\n      \"Bash(find *)\",\n      \"Bash(grep *)\",\n      \"Bash(head *)\",\n      \"Bash(tail *)\",\n      \"Bash(wc *)\",\n      \"Bash(sort *)\",\n      \"Bash(uniq *)\",\n      \"Bash(diff *)\",\n      \"Bash(which *)\",\n      \"Bash(pwd *)\",\n      \"Bash(date *)\",\n      \"Bash(mkdir *)\",\n      \"Bash(basename *)\",\n      \"Bash(dirname *)\",\n      \"Bash(realpath *)\",\n      \"Bash(jq *)\",\n      \"Bash(curl *)\",\n      \"Bash(tree *)\",\n      \"Bash(sed *)\",\n      \"Bash(awk *)\",\n      \"Bash(cut *)\",\n      \"Bash(tr *)\",\n      \"Bash(tee *)\",\n      \"Bash(echo *)\",\n      \"Bash(printf *)\",\n      \"Bash(env *)\",\n      \"Bash(printenv *)\",\n      \"Bash(uname *)\",\n      \"Bash(file *)\",\n      \"Bash(stat *)\",\n      \"Bash(du *)\",\n      \"Bash(id *)\",\n      \"Bash(whoami *)\",\n      \"Bash(php *)\",\n      \"Bash(composer *)\",\n      \"Bash(python3 *)\",\n      \"Bash(python *)\",\n      \"Bash(pip *)\",\n      \"Bash(pip3 *)\"\n    ],\n    \"deny\": [\n      \"Read(**/.env)\",\n      \"Read(**/.env.local)\",\n      \"Read(**/secrets/**)\",\n      \"Read(**/*.key)\",\n      \"Read(**/*.pem)\",\n      \"Read(**/*.p12)\",\n      \"Read(**/.credentials*)\",\n      \"Edit(**/.env)\",\n      \"Edit(**/.env.local)\",\n      \"Edit(**/secrets/**)\",\n      \"Bash(sudo *)\",\n      \"Bash(rm -rf /)\",\n      \"Bash(rm -rf / *)\",\n      \"Bash(rm -rf ~)\",\n      \"Bash(rm -rf ~ *)\",\n      \"Bash(rm -rf $HOME)\",\n      \"Bash(rm -rf $HOME *)\",\n      \"Bash(> /dev *)\",\n      \"Bash(dd if= *)\",\n      \"Bash(mkfs *)\",\n      \"Bash(eval *)\",\n      \"Bash(chmod 777 *)\",\n      \"Bash(chmod -R 777 *)\",\n      \"Bash(git push --force origin main *)\",\n      \"Bash(git push --force origin master *)\",\n      \"Bash(git push -f origin main *)\",\n      \"Bash(git push -f origin master *)\"\n    ],\n    \"ask\": [\n      \"Bash(git clean *)\",\n      \"Bash(docker volume rm *)\",\n      \"Bash(docker system prune *)\"\n    ]\n  },\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_SESSION_START__\"],\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_NOTIFY__\"],\n            \"timeout\": 10,\n            \"async\": true\n          }\n        ]\n      }\n    ],\n    \"PostToolUseFailure\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo '{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PostToolUseFailure\\\",\\\"additionalContext\\\":\\\"Last bash command failed. Repository / file state may have shifted \\u2014 re-read affected files before retrying. If the failure is a missing dependency or env mismatch, surface it to the user rather than retrying blindly.\\\"}}'\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"SubagentStop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"You are a quality gate for subagent outputs in a multi-agent code-analysis pipeline.\\n\\nEvaluate the subagent's `last_assistant_message` field (in the JSON below) against these requirements:\\n\\n1. ALLOW (return `{}`): Mode-selection or no-issues responses. Examples: \\\"Which mode do you prefer\\\", \\\"select an option\\\", \\\"no issues / problems / violations / blockers found\\\".\\n\\n2. ALLOW (return `{}`): Output contains at least one concrete file:line citation \\u2014 e.g. `src/auth.ts:42`, `lib/db.ts:100-115`, or path references that include line numbers.\\n\\n3. BLOCK (return `{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"<one-line explanation>\\\"}`): Output claims about code or findings WITHOUT concrete file:line citations. Vague references like \\\"the auth handler\\\" or \\\"near the database code\\\" are not acceptable as the only evidence.\\n\\nSubagent invocation JSON:\\n$ARGUMENTS\\n\\nReturn ONLY the JSON decision (no commentary, no markdown fences).\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  },\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"__DOCKS_KIT_STATUSLINE__\",\n    \"refreshInterval\": 5\n  },\n  \"enabledPlugins\": {\n    \"docks@docks\": true,\n    \"plan-lifecycle@docks\": true,\n    \"effect-kit@docks\": true,\n    \"php-lsp@claude-plugins-official\": true,\n    \"typescript-lsp@claude-plugins-official\": true\n  },\n  \"extraKnownMarketplaces\": {\n    \"docks\": {\n      \"source\": {\n        \"source\": \"github\",\n        \"repo\": \"DocksDocks/docks\"\n      }\n    }\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"showThinkingSummaries\": true,\n  \"viewMode\": \"default\",\n  \"theme\": \"dark-daltonized\",\n  \"skipDangerousModePermissionPrompt\": true\n}\n",
   "SoT/.claude/bin/statusline.mjs": "const ESC = \"\\x1b[\"\nconst PIPE = `${ESC}90m | ${ESC}0m`\nconst DOT = `${ESC}90m • ${ESC}0m`\nconst DIM = `${ESC}2m${ESC}38;2;156;162;175m`\n\nfunction isRecord(value) {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n}\n\nfunction finitePercentage(value) {\n  return typeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= 100\n    ? value\n    : undefined\n}\n\nfunction roundHalfEven(value) {\n  const lower = Math.floor(value)\n  const fraction = value - lower\n  if (fraction < 0.5) return lower\n  if (fraction > 0.5) return lower + 1\n  return lower % 2 === 0 ? lower : lower + 1\n}\n\nfunction pathBasename(path) {\n  const parts = path.split(/[\\\\/]+/).filter((part) => part !== \"\")\n  return parts.at(-1) ?? \"\"\n}\n\nfunction modelName(input) {\n  const model = isRecord(input.model) && typeof input.model.display_name === \"string\"\n    ? input.model.display_name\n    : \"\"\n  const suffix = model.indexOf(\" (\")\n  return suffix === -1 ? model : model.slice(0, suffix)\n}\n\nfunction workingDirectory(input, cwd) {\n  if (isRecord(input.workspace) && typeof input.workspace.current_dir === \"string\" && input.workspace.current_dir !== \"\") {\n    return input.workspace.current_dir\n  }\n  if (typeof input.cwd === \"string\" && input.cwd !== \"\") return input.cwd\n  return cwd\n}\n\nfunction compactWindow(env, total) {\n  const raw = env.CLAUDE_CODE_AUTO_COMPACT_WINDOW\n  if (typeof raw !== \"string\" || !/^[0-9]+$/.test(raw)) return total\n  const parsed = Number(raw)\n  return Number.isSafeInteger(parsed) && parsed >= 1000 && parsed < total ? parsed : total\n}\n\nfunction formatTokensK(value) {\n  if (value < 1000) return `${value}k`\n  if (value % 1000 === 0) return `${value / 1000}M`\n  return `${(roundHalfEven(value / 100) / 10).toFixed(1)}M`\n}\n\nfunction contextSegment(input, env) {\n  if (!isRecord(input.context_window)) return \"\"\n  const used = finitePercentage(input.context_window.used_percentage)\n  if (used === undefined) return \"\"\n\n  const total = input.context_window.context_window_size\n  if (typeof total !== \"number\" || !Number.isFinite(total) || total <= 0) {\n    return `${ESC}38;2;130;160;230mctx ${roundHalfEven(used)}%${ESC}0m`\n  }\n\n  const usedK = roundHalfEven((used / 100) * (total / 1000))\n  const effectiveK = Math.trunc(compactWindow(env, total) / 1000)\n  if (effectiveK <= 0) return `${ESC}38;2;130;160;230mctx ${roundHalfEven(used)}%${ESC}0m`\n  const effectivePercentage = roundHalfEven((usedK / effectiveK) * 100)\n  return `${ESC}38;2;130;160;230mctx ${effectivePercentage}%${ESC}0m ${DIM}(${formatTokensK(usedK)}/${formatTokensK(effectiveK)})${ESC}0m`\n}\n\nfunction resetDelta(value, nowMs) {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) return \"\"\n  const seconds = Math.trunc(value) - Math.floor(nowMs / 1000)\n  if (seconds <= 0) return \"now\"\n  const days = Math.trunc(seconds / 86_400)\n  if (days > 0) return `${days}d`\n  const hours = Math.trunc((seconds % 86_400) / 3_600)\n  if (hours > 0) return `${hours}h`\n  return `${Math.trunc((seconds % 3_600) / 60)}m`\n}\n\nfunction quotaWindow(value, label, color, nowMs) {\n  if (!isRecord(value)) return \"\"\n  const used = finitePercentage(value.used_percentage)\n  if (used === undefined) return \"\"\n  const delta = resetDelta(value.resets_at, nowMs)\n  const reset = delta === \"\" ? \"\" : ` ${DIM}(${delta})${ESC}0m`\n  return `${ESC}38;2;${color}m${label} ${roundHalfEven(used)}%${ESC}0m${reset}`\n}\n\nfunction decodeStdout(result) {\n  const stdout = result?.stdout\n  if (stdout === undefined || stdout === null) return \"\"\n  return typeof stdout === \"string\" ? stdout : stdout.toString()\n}\n\nfunction resolveBranch(directory, which, spawnSync) {\n  const git = which(\"git\")\n  if (typeof git !== \"string\" || git === \"\") return \"\"\n  const commands = [\n    [git, \"-C\", directory, \"symbolic-ref\", \"--short\", \"HEAD\"],\n    [git, \"-C\", directory, \"rev-parse\", \"--short\", \"HEAD\"]\n  ]\n  for (const command of commands) {\n    try {\n      const result = spawnSync(command, { stdin: \"ignore\", stdout: \"pipe\", stderr: \"ignore\" })\n      if (result?.success === true) return decodeStdout(result).trim()\n    } catch {\n      return \"\"\n    }\n  }\n  return \"\"\n}\n\nexport function formatStatusline(input, options = {}) {\n  if (!isRecord(input)) return \"\"\n  const env = isRecord(options.env) ? options.env : process.env\n  const nowMs = typeof options.nowMs === \"number\" ? options.nowMs : Date.now()\n  const cwd = typeof options.cwd === \"string\" ? options.cwd : process.cwd()\n  const branch = typeof options.branch === \"string\" ? options.branch : \"\"\n  const directory = workingDirectory(input, cwd)\n\n  const model = `${ESC}38;5;208m${ESC}1m${modelName(input)}${ESC}22m${ESC}0m`\n  const folder = `${ESC}1m${ESC}38;2;76;208;222m${pathBasename(directory)}${ESC}22m${ESC}0m`\n  const branchSegment = branch === \"\" ? \"\" : `${DOT}${ESC}1m${ESC}38;2;192;103;222m${branch}${ESC}22m${ESC}0m`\n  const context = contextSegment(input, env)\n\n  const rateLimits = isRecord(input.rate_limits) ? input.rate_limits : {}\n  const fiveHour = quotaWindow(rateLimits.five_hour, \"5h\", \"100;200;200\", nowMs)\n  const sevenDay = quotaWindow(rateLimits.seven_day, \"7d\", \"230;180;90\", nowMs)\n  const quota = fiveHour === \"\" && sevenDay === \"\"\n    ? \"\"\n    : `${PIPE}${fiveHour}${fiveHour !== \"\" && sevenDay !== \"\" ? DOT : \"\"}${sevenDay}`\n\n  return `${model}${PIPE}${folder}${branchSegment}${context === \"\" ? \"\" : `${PIPE}${context}`}${quota}`\n}\n\nexport async function main(options = {}) {\n  const readStdin = options.readStdin ?? (() => Bun.stdin.text())\n  const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value))\n  let raw\n  try {\n    raw = await readStdin()\n  } catch {\n    return 0\n  }\n\n  let input\n  try {\n    input = JSON.parse(raw)\n  } catch {\n    return 0\n  }\n  if (!isRecord(input)) return 0\n\n  const cwd = typeof options.cwd === \"string\" ? options.cwd : process.cwd()\n  const directory = workingDirectory(input, cwd)\n  const branch = resolveBranch(\n    directory,\n    options.which ?? ((name) => Bun.which(name)),\n    options.spawnSync ?? ((argv, spawnOptions) => Bun.spawnSync(argv, spawnOptions))\n  )\n  const output = formatStatusline(input, {\n    env: options.env ?? process.env,\n    nowMs: options.nowMs ?? Date.now(),\n    cwd,\n    branch\n  })\n  if (output !== \"\") writeStdout(`${output}\\n`)\n  return 0\n}\n\nif (import.meta.main) process.exit(await main())\n",
   "SoT/.claude/bin/session-start.mjs": "import { readFileSync } from \"node:fs\"\nimport { homedir } from \"node:os\"\n\nfunction isRecord(value) {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n}\n\nfunction nonEmpty(value, fallback) {\n  return typeof value === \"string\" && value !== \"\" ? value : fallback\n}\n\nfunction pad(value) {\n  return String(value).padStart(2, \"0\")\n}\n\nfunction configuredEffort(home, readText) {\n  try {\n    const parsed = JSON.parse(readText(`${home}/.claude/settings.json`))\n    return isRecord(parsed) ? nonEmpty(parsed.effortLevel, \"default\") : \"default\"\n  } catch {\n    return \"default\"\n  }\n}\n\nfunction localZone(now) {\n  const part = new Intl.DateTimeFormat(\"en-US\", { timeZoneName: \"short\" })\n    .formatToParts(now)\n    .find((value) => value.type === \"timeZoneName\")\n  return part?.value ?? \"\"\n}\n\nexport function sessionStartLines(options = {}) {\n  const env = isRecord(options.env) ? options.env : process.env\n  const now = options.now instanceof Date ? options.now : new Date()\n  const home = typeof options.home === \"string\" ? options.home : homedir()\n  const readText = options.readText ?? ((path) => readFileSync(path, \"utf8\"))\n  const weekday = new Intl.DateTimeFormat(\"en-US\", { weekday: \"long\" }).format(now)\n  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`\n  const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`\n  const effort = nonEmpty(env.CLAUDE_CODE_EFFORT_LEVEL, configuredEffort(home, readText))\n  const context = env.CLAUDE_CODE_DISABLE_1M_CONTEXT === \"1\" ? \"200K\" : \"1M\"\n  const compactWindow = nonEmpty(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, \"full\")\n  const subagent = nonEmpty(env.CLAUDE_CODE_SUBAGENT_MODEL, \"default\")\n  return [\n    `[CONTEXT] Current date: ${weekday}, ${date} ${time} ${localZone(now)}`,\n    `[CONFIG] Context: ${context} | Compact-window: ${compactWindow} | Effort: ${effort} | Thinking: adaptive | Subagent: ${subagent}`\n  ]\n}\n\nexport async function main(options = {}) {\n  const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value))\n  writeStdout(`${sessionStartLines(options).join(\"\\n\")}\\n`)\n  return 0\n}\n\nif (import.meta.main) process.exit(await main())\n",
-  "SoT/.claude/bin/notify.mjs": "const DEFAULT_SOUND = `${import.meta.dir}/../notification.mp3`\n\nexport function selectPlayer(options = {}) {\n  const platform = options.platform ?? process.platform\n  const sound = options.sound ?? DEFAULT_SOUND\n  const which = options.which ?? ((name) => Bun.which(name))\n  if (platform === \"darwin\") {\n    const afplay = which(\"afplay\")\n    if (typeof afplay === \"string\" && afplay !== \"\") return [afplay, sound]\n  }\n  const ffplay = which(\"ffplay\")\n  if (typeof ffplay === \"string\" && ffplay !== \"\") {\n    return [ffplay, \"-nodisp\", \"-autoexit\", \"-loglevel\", \"quiet\", sound]\n  }\n  const paplay = which(\"paplay\")\n  if (typeof paplay === \"string\" && paplay !== \"\") return [paplay, sound]\n  const aplay = which(\"aplay\")\n  if (typeof aplay === \"string\" && aplay !== \"\") return [aplay, \"-q\", sound]\n  return undefined\n}\n\nexport async function main(options = {}) {\n  const sound = options.sound ?? DEFAULT_SOUND\n  const fileExists = options.fileExists ?? ((path) => Bun.file(path).exists())\n  if (!await fileExists(sound)) return 0\n  const command = selectPlayer({ ...options, sound })\n  if (command === undefined) return 0\n  const spawnSync = options.spawnSync ?? ((argv, spawnOptions) => Bun.spawnSync(argv, spawnOptions))\n  const result = spawnSync(command, { stdin: \"ignore\", stdout: \"ignore\", stderr: \"ignore\" })\n  return typeof result.exitCode === \"number\" ? result.exitCode : 1\n}\n\nif (import.meta.main) process.exit(await main())\n",
+  "SoT/.claude/bin/notify.mjs": "const DEFAULT_SOUND = `${import.meta.dir}/../notification.mp3`\n\nexport function selectPlayer(options = {}) {\n  const platform = options.platform ?? process.platform\n  const sound = options.sound ?? DEFAULT_SOUND\n  const which = options.which ?? ((name) => Bun.which(name))\n  if (platform === \"darwin\") {\n    const afplay = which(\"afplay\")\n    if (typeof afplay === \"string\" && afplay !== \"\") return [afplay, sound]\n  }\n  const ffplay = which(\"ffplay\")\n  if (typeof ffplay === \"string\" && ffplay !== \"\") {\n    return [ffplay, \"-nodisp\", \"-autoexit\", \"-loglevel\", \"quiet\", sound]\n  }\n  const paplay = which(\"paplay\")\n  if (typeof paplay === \"string\" && paplay !== \"\") return [paplay, sound]\n  const aplay = which(\"aplay\")\n  if (typeof aplay === \"string\" && aplay !== \"\") return [aplay, \"-q\", sound]\n  return undefined\n}\n\nexport async function main(options = {}) {\n  const sound = options.sound ?? DEFAULT_SOUND\n  const fileExists = options.fileExists ?? ((path) => Bun.file(path).exists())\n  if (!await fileExists(sound)) return 0\n  const command = selectPlayer({ ...options, sound })\n  if (command === undefined) return 0\n  const spawnSync = options.spawnSync ?? ((argv, spawnOptions) => Bun.spawnSync(argv, spawnOptions))\n  spawnSync(command, { stdin: \"ignore\", stdout: \"ignore\", stderr: \"ignore\" })\n  return 0\n}\n\nif (import.meta.main) process.exit(await main())\n",
   "SoT/.codex/AGENTS.md": "# AGENTS.md\n\n## Research Before Implementation\n\nBefore writing or modifying code that uses an API, hook, method, or config surface you have not verified in this session, research current documentation first.\n\nResearch workflow:\n1. Prefer official documentation and primary sources for the specific library, framework, or API.\n2. If a local docs or MCP tool is available, use it before broad web search.\n3. Only then proceed to implementation.\n\nResearch when:\n- Installing or configuring a dependency.\n- Using an API, hook, method, or pattern not verified in this session.\n- Upgrading or migrating between versions.\n- Any task where relying on memory could cause stale syntax or behavior.\n\nDo not:\n- Assume API signatures, method names, or config options from memory.\n- Generate framework code without checking current docs first.\n- Skip research because the library seems familiar.\n\n<constraint>\nResearch the codebase before editing. Never change code you have not read.\n</constraint>\n\n## Agentic Harness Heuristics\n\nModel-agnostic operating rules for coding-agent work.\n\n1. Persistence. Keep going until the user's request is actually handled. Only yield when the problem is solved or a concrete blocker is identified. Resolve in the fewest useful tool loops — once you can answer the core request with evidence, answer. Before ending a turn, check the last paragraph: if it is a plan, a question you can answer yourself, or a promise of work not done, do that work now.\n2. Default to parallel. When multiple reads, searches, inspections, or independent checks can run without depending on each other, run them together.\n3. Multi-pass search. First-pass search often misses — vary the wording before concluding something does not exist.\n4. Trace symbols. Before modifying a symbol, trace its definition and usages. Do not infer behavior from one call site.\n5. Linter-loop 3-strike rule. Do not loop more than 3 times fixing the same lint/test failure without reassessing the diagnosis.\n6. Read-before-edit TTL. If you have not read a file recently, re-read it before editing. User edits can make cached context stale.\n7. Big-file rule. For files over 1000 lines, prefer targeted search plus scoped reads over whole-file reads.\n8. Task hygiene. Track meaningful deliverables, not operational sub-steps. Mark work complete as soon as it is done.\n9. Literal-instruction rule. Treat explicit user requirements as checklists with success criteria. Do not silently broaden scope.\n10. Context hygiene. Prefer a fresh session at task boundaries over carrying stale context; preserve useful state before quality decays. Never stop, summarize, or suggest a new session on account of context limits.\n11. Autonomy calibration. For minor choices (naming, formatting, defaults, equivalent approaches), pick a reasonable option and note it — do not ask. Ask first only for scope changes, destructive actions, or decisions that change the deliverable. When the user is describing a problem or asking a question rather than requesting a change, the deliverable is your assessment — report findings and stop; do not apply fixes until asked.\n12. Capability triggering. Search or fetch current documentation when the answer depends on current or version-specific information. When work fans out across independent items, parallelize or delegate; never delegate work you can complete directly. For verification, prefer a fresh-context check over self-critique. On long tasks, keep running notes and re-read them between phases.\n\n<constraint>\nTreat these heuristics as protocol. If a turn violates an applicable rule, self-correct before continuing.\n</constraint>\n\nReuse before invention: inventory existing code, components, conventions, and dependencies; extend them instead of creating a parallel pattern. Load only the narrow skills supported by the task and repository evidence. If a request establishes a new React/Tailwind system and no convention exists, prefer current shadcn/ui `base-*` components backed by Base UI; otherwise preserve the existing stack. Treat probe, production access, publish, push, release, and deploy as literal current-request effects—never infer external authority from a plan, schedule, review, or old receipt.\n\nFor Docks plan reviews, cross-company review is standing-authorized; do not ask for export consent. This never overrides a host or platform security denial.\n\nUse a narrow-to-broad verification ladder: direct acceptance while iterating, focused regressions next, and one full CI at the pre-commit or release boundary. Reuse still-matching evidence; rerun full CI only after a relevant edit invalidates it.\n\n<constraint>\nNo secrets in committed config. Treat plugin marketplaces, installers, and downloaded artifacts as untrusted until verified.\n</constraint>\n",
   "SoT/.codex/config.toml": "model = \"gpt-5.6-sol\"\nmodel_reasoning_effort = \"high\"\nplan_mode_reasoning_effort = \"high\"\nmodel_reasoning_summary = \"concise\"\nmodel_verbosity = \"low\"\npersonality = \"pragmatic\"\nweb_search = \"live\"\nproject_doc_max_bytes = 131072\napproval_policy = \"on-request\"\nsandbox_mode = \"workspace-write\"\napprovals_reviewer = \"auto_review\"\n\n[sandbox_workspace_write]\nnetwork_access = true\n\n[features]\nmemories = true\n\n[memories]\ndedicated_tools = true\nmax_rollout_age_days = 30\n\n[agents]\nmax_threads = 12\nmax_depth = 2\n\n[tui]\nstatus_line_use_colors = true\nstatus_line = [\n  \"model-with-reasoning\",\n  \"current-dir\",\n  \"git-branch\",\n  \"context-used\",\n  \"five-hour-limit\",\n  \"weekly-limit\",\n]\n\n[plugins.\"docks@docks\"]\nenabled = true\n\n[plugins.\"plan-lifecycle@docks\"]\nenabled = true\n\n[plugins.\"effect-kit@docks\"]\nenabled = true\n",
   "SoT/.codex/plugins/marketplace.json": "{\n  \"name\": \"docks\",\n  \"interface\": {\n    \"displayName\": \"DocksDocks\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"docks\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/DocksDocks/docks.git\",\n        \"path\": \"./plugins/docks\",\n        \"ref\": \"main\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Productivity\"\n    },\n    {\n      \"name\": \"effect-kit\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/DocksDocks/docks.git\",\n        \"path\": \"./plugins/effect-kit\",\n        \"ref\": \"main\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Productivity\"\n    },\n    {\n      \"name\": \"plan-lifecycle\",\n      \"source\": {\n        \"source\": \"git-subdir\",\n        \"url\": \"https://github.com/DocksDocks/docks.git\",\n        \"path\": \"./plugins/plan-lifecycle\",\n        \"ref\": \"main\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Productivity\"\n    }\n  ]\n}\n",
@@ -40,4 +40,4 @@ export const GENERATED_PAYLOAD_PATHS = [
   "notification.mp3"
 ] as const
 
-export const GENERATED_PAYLOAD_HASH = "dd259569b864fe7c2e1c54e8e0155d529b1e2f0f2b515f32178976c55ff9e7e3"
+export const GENERATED_PAYLOAD_HASH = "66c1b63b01b6c1ca6a39a1fe96ed8cda72774e9dcc6bfdc0a4ad6abe9f3a028e"

package/cli/src/kitHome.ts

@@ -10,6 +10,47 @@ const isKitHome = (dir: string): boolean => {
   }
 }
 
+const explicitKitHome = (dir: string, source: string): string => {
+  const packageJson = join(dir, "package.json")
+  let text: string
+  try {
+    text = readFileSync(packageJson, "utf8")
+  } catch (error) {
+    const code =
+      typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined
+    if (code === "ENOENT") {
+      throw new Error(`DOCKS_KIT_HOME=${source} does not contain package.json`)
+    }
+    const detail = error instanceof Error ? error.message : String(error)
+    const category = code === undefined ? "" : ` (${code})`
+    throw new Error(
+      `DOCKS_KIT_HOME=${source} package.json cannot be read${category}: ${detail}`
+    )
+  }
+
+  let manifest: unknown
+  try {
+    manifest = JSON.parse(text)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new Error(`DOCKS_KIT_HOME=${source} package.json contains invalid JSON: ${detail}`)
+  }
+
+  if (
+    typeof manifest !== "object" ||
+    manifest === null ||
+    !("name" in manifest) ||
+    manifest.name !== "docks-kit"
+  ) {
+    throw new Error(
+      `DOCKS_KIT_HOME=${source} is not a docks-kit package root (package.json name must be "docks-kit")`
+    )
+  }
+  return dir
+}
+
 const findKitHome = (start: string | undefined): string | undefined => {
   if (start === undefined || start === "") return undefined
   let dir = resolve(start)
@@ -37,11 +78,7 @@ export interface KitHomeSources {
  */
 export const resolveKitHome = (sources: KitHomeSources): string => {
   if (sources.env !== undefined && sources.env !== "") {
-    const envHome = resolve(sources.env)
-    if (isKitHome(envHome)) return envHome
-    throw new Error(
-      `DOCKS_KIT_HOME=${sources.env} is not a docks-kit package root (package.json name must be "docks-kit")`
-    )
+    return explicitKitHome(resolve(sources.env), sources.env)
   }
 
   return (

package/cli/src/main.ts

@@ -14,6 +14,7 @@ import { toolchainCommand } from "./commands/toolchain"
 import { updateCommand } from "./commands/update"
 import { GENERATED_PACKAGE_VERSION } from "./generated/sotPayload"
 import { prepareArgv } from "./argv"
+import { runEngineNative } from "./engine-native"
 
 
 const root = Command.make("docks-kit", {}, () =>
@@ -64,8 +65,17 @@ const bareVersionFormatter: CliOutput.Formatter = {
 // PUBLIC engine execution lives at the engine.ts seam after the CLI has
 // parsed/normalized pickers, --flag value forms, and non-engine commands.
 if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
-  const { runEngineNative } = await import("./engine-native")
-  process.exit(await runEngineNative(process.argv.slice(2)))
+  const rawArgs = process.argv.slice(2)
+  const rawOperation = rawArgs.join(" ") || "default"
+  try {
+    process.exit(await runEngineNative(rawArgs))
+  } catch (error) {
+    let detail = "unknown error"
+    if (error instanceof Error && error.message !== "") detail = error.message
+    else if (typeof error === "string" && error !== "") detail = error
+    process.stderr.write(`docks-kit raw operation '${rawOperation}' failed: ${detail}\n`)
+    process.exit(1)
+  }
 }
 
 // Validate and normalize before parsing because the kit refuses to guess at unrecognized

package/cli/src/manifests.ts

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, readlinkSync, existsSync } from "node:fs"
 import { homedir } from "node:os"
-import { join } from "node:path"
+import { dirname, join, resolve } from "node:path"
+import { pluginUserScopeInstalled } from "./engine-native/claudeSync"
 import { payloadText } from "./payload"
 
 export { homedir }
@@ -36,18 +37,22 @@ export const deployedClaudeSettings = (): any | undefined => {
   return existsSync(p) ? readJson(p) : undefined
 }
 
-const tomlModelText = (text: string): string | undefined => {
-  const m = text.match(/^model\s*=\s*"([^"]+)"/m)
-  return m?.[1]
+export function topLevelTomlString(text: string, setting: string): string | undefined {
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*\[/.test(line)) return undefined
+    const assignment = line.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*"([^"]+)"/)
+    if (assignment?.[1] === setting) return assignment[2]
+  }
+  return undefined
 }
 
 const tomlModel = (path: string): string | undefined => {
   if (!existsSync(path)) return undefined
-  return tomlModelText(readFileSync(path, "utf8"))
+  return topLevelTomlString(readFileSync(path, "utf8"), "model")
 }
 
 export const sotCodexModel = (): string | undefined =>
-  tomlModelText(payloadText("SoT/.codex/config.toml"))
+  topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model")
 
 export const deployedCodexModel = (): string | undefined =>
   tomlModel(join(homedir(), ".codex", "config.toml"))
@@ -67,7 +72,7 @@ export const pluginsView = (): Array<{
   return [...names].sort().map((plugin) => ({
     plugin,
     sot: plugin in sot ? (sot[plugin] ? "true" : "false") : "absent",
-    installed: plugin in installed
+    installed: pluginUserScopeInstalled(installedPath, plugin)
   }))
 }
 
@@ -83,7 +88,8 @@ export const skillsView = (): Array<{
     .map((l) => l.replace(/#.*$/, "").trim())
     .filter((l) => l.length > 0)
     .map((slug) => slug.split("/").pop() as string)
-  const skillsDir = join(homedir(), ".agents", "skills")
+  const home = homedir()
+  const skillsDir = join(home, ".agents", "skills")
   const installed = existsSync(skillsDir)
     ? readdirSync(skillsDir, { withFileTypes: true })
         .filter((e) => e.isDirectory())
@@ -91,10 +97,11 @@ export const skillsView = (): Array<{
     : []
   const names = new Set([...declared, ...installed])
   return [...names].sort().map((skill) => {
-    const link = join(homedir(), ".claude", "skills", skill)
+    const link = join(home, ".claude", "skills", skill)
     let claudeSymlink = false
     try {
-      claudeSymlink = readlinkSync(link).includes(".agents/skills")
+      const target = resolve(dirname(link), readlinkSync(link))
+      claudeSymlink = target === resolve(skillsDir, skill) && existsSync(target)
     } catch {
       /* not a symlink or missing */
     }

package/cli/src/payload.ts

@@ -1,5 +1,3 @@
-import { existsSync } from "node:fs"
-import { join } from "node:path"
 import {
   GENERATED_PAYLOAD_BASE64,
   GENERATED_PAYLOAD_PATHS,
@@ -22,7 +20,6 @@ export function payloadPaths(prefix: string): ReadonlyArray<PayloadPath> {
   return GENERATED_PAYLOAD_PATHS.filter((path) => path.startsWith(prefix))
 }
 
-export function payloadDisplayPath(path: PayloadPath, kitHome?: string): string {
-  if (kitHome === undefined || !existsSync(join(kitHome, "package.json"))) return `embedded:${path}`
-  return `${kitHome.replace(/[\\/]+$/, "")}/${path}`
+export function payloadDisplayPath(path: PayloadPath): string {
+  return `embedded:${path}`
 }

package/docks-kit

@@ -30,12 +30,12 @@ if [[ -x "$REPO_DIR/cli/dist/$KIT_BIN" ]]; then
       break
     fi
   done < "$REPO_DIR/package.json"
-  IFS= read -r BIN_VERSION < <("$REPO_DIR/cli/dist/$KIT_BIN" --version 2>/dev/null || true)
+  BIN_VERSION="$("$REPO_DIR/cli/dist/$KIT_BIN" --version 2>/dev/null || true)"
   BIN_VERSION="${BIN_VERSION%$'\r'}"
-  if [[ -z "$CHECKOUT_VERSION" || "$BIN_VERSION" == "$CHECKOUT_VERSION" ]]; then
+  if [[ -n "$CHECKOUT_VERSION" && "$BIN_VERSION" == "$CHECKOUT_VERSION" ]]; then
     exec "$REPO_DIR/cli/dist/$KIT_BIN" "$@"
   fi
-  echo "[docks-kit] ignoring stale cli/dist/$KIT_BIN ${BIN_VERSION:-<unknown>}; checkout is $CHECKOUT_VERSION — running from source" >&2
+  echo "[docks-kit] ignoring stale cli/dist/$KIT_BIN ${BIN_VERSION:-<unknown>}; checkout is ${CHECKOUT_VERSION:-<unknown>} — running from source" >&2
 fi
 
 # Locate bun: PATH, then the known install locations that sit off the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",