docks-kit 0.8.2 → 0.10.0

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

@@ -32,6 +32,7 @@ import { mergeSettings, reconcileSettings } from "./settings"
 import { ensure, field } from "./toolchain"
 import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
 import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
+import { ensureSessionRelayCli } from "./sessionRelayCli"
 
 export type ClaudeRuntimeState =
   | { readonly kind: "ready"; readonly paths: ClaudeRuntimePaths }
@@ -61,8 +62,7 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
   }
   const materialized = materializeClaudeSettings(
     template,
-    runtime.kind === "ready" ? runtime.paths : undefined,
-    ctx.services.platform
+    runtime.kind === "ready" ? runtime.paths : undefined
   )
   const prepared = ctx.dryRun ? undefined : prepareClaudeSettings(ctx, claudeDir, materialized)
 
@@ -82,6 +82,7 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
   syncClaudeAdvisor(ctx, ctx.claudeAdvisor)
   syncClaudeJson(ctx)
   syncConnectorEnv(ctx)
+  ensureSessionRelayCli(ctx)
   syncPlugins(ctx, claudeDir)
   syncOptionalPlugins(ctx, claudeDir)
   syncLspServers(ctx)
@@ -148,12 +149,7 @@ function syncRtk(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  if (ctx.services.platform.isWindows()) {
-    if (ctx.services.deps.probe("rtk").state === "missing") {
-      warn("rtk not installed — the kit's auto-install is Unix-only. Install natively (winget, or the rtk-*-windows-msvc.zip release), then re-run sync")
-      return
-    }
-  } else if (ensureRtk(ctx, "cannot download RTK installer; continuing sync without RTK", 0) !== 0) {
+  if (ensureRtk(ctx, "cannot download RTK installer; continuing sync without RTK", 0) !== 0) {
     warn("RTK bootstrap failed — continuing sync without it")
   }
 
@@ -410,32 +406,7 @@ function syncClaudeJson(ctx: Ctx): void {
 // -------------------------------------------------------- connector env ----
 
 function syncConnectorEnv(ctx: Ctx): void {
-  const { change, echo, verbose, warn } = ctx.services.logger
-  // win32: Claude Code launches from PowerShell/GUI, so the flag must be a
-  // real user env var (setx), not a Git-Bash-only shell-rc export. Never
-  // clobbers an existing value (set =true yourself to keep connectors).
-  if (ctx.services.platform.isWindows()) {
-    const existing = spawnSync("reg", ["query", "HKCU\\Environment", "/v", "ENABLE_CLAUDEAI_MCP_SERVERS"], {
-      stdio: "ignore"
-    })
-    if (existing.error === undefined && existing.status === 0) {
-      if (ctx.dryRun) echo("[dry-run] ENABLE_CLAUDEAI_MCP_SERVERS already in user environment — would skip")
-      else verbose("claude.ai connectors: ENABLE_CLAUDEAI_MCP_SERVERS already set in user environment (left as-is)")
-      return
-    }
-    if (ctx.dryRun) {
-      echo("[dry-run] setx ENABLE_CLAUDEAI_MCP_SERVERS false (user environment)")
-      return
-    }
-    const res = spawnSync("setx", ["ENABLE_CLAUDEAI_MCP_SERVERS", "false"], { stdio: "ignore" })
-    if (res.error === undefined && res.status === 0) {
-      change("claude.ai connectors disabled via setx (open a new terminal to apply)")
-      ctx.nextStepTriggers.claudeRestart = true
-    } else {
-      warn("setx ENABLE_CLAUDEAI_MCP_SERVERS false failed — set it manually in System Properties > Environment Variables")
-    }
-    return
-  }
+  const { change, echo, verbose } = ctx.services.logger
 
   const line = "export ENABLE_CLAUDEAI_MCP_SERVERS=false"
   const marker = "# docks-kit: disable claude.ai cloud MCP connectors (set =true to keep them)"

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

@@ -13,6 +13,7 @@ import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "
 import { sessionRelayReadiness } from "./sessionRelayReadiness"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
+import { ensureSessionRelayCli } from "./sessionRelayCli"
 
 export function codexSync(ctx: Ctx): void {
   const codexDir = p(ctx.home, ".codex")
@@ -28,6 +29,7 @@ export function codexSync(ctx: Ctx): void {
   syncAgentsMd(ctx, renderDefaultWorkflowInstructions(payloadText("SoT/.codex/AGENTS.md")), p(codexDir, "AGENTS.md"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
   removeLegacyDocksMarketplace(ctx, userConfig)
+  ensureSessionRelayCli(ctx)
   syncPlugins(ctx, sotConfig)
 }
 
@@ -84,7 +86,7 @@ function bwrapSupportedOs(ctx: Ctx): boolean {
   const { warn } = ctx.services.logger
   const pn = ctx.services.platform.name()
   if (pn === "linux") return true
-  if (pn === "darwin" || pn === "windows") return false
+  if (pn === "darwin") return false
   warn("Unknown OS — skipping bubblewrap check; Codex sandbox may not work")
   return false
 }

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

@@ -29,6 +29,7 @@ export type ToolId =
   | "bwrap"
   | "agent-browser"
   | "effect-solutions"
+  | "session-relay"
   | "chrome-for-testing"
   | "ffplay"
   | "intelephense"
@@ -111,34 +112,29 @@ const home = (): string => {
   return envHome !== undefined && envHome !== "" ? envHome : homedir()
 }
 
-const absoluteWindowsExe = (path: string): boolean =>
-  /\.exe$/i.test(path) && (/^[A-Za-z]:[\\/]/.test(path) || /^\\\\/.test(path))
 
 // The resolved path gets persisted into global direct-exec hooks, so a
 // relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
 // break outside the sync working directory.
-const absoluteExecutable = (path: string, platform: NodeJS.Platform): boolean =>
-  platform === "win32" ? absoluteWindowsExe(path) : isAbsolute(path)
 
-const findBun = (exec: ProbeExecutor, platform: NodeJS.Platform = rawPlatform()): { command: string; path: string } | undefined => {
+const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
   const onPath = exec.which("bun")
-  if (onPath !== "" && absoluteExecutable(onPath, platform)) {
-    return { command: platform === "win32" ? onPath : "bun", path: onPath }
+  if (onPath !== "" && isAbsolute(onPath)) {
+    return { command: "bun", path: onPath }
   }
   const root =
     process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
       ? process.env["BUN_INSTALL"]!
       : p(home(), ".bun")
-  const name = platform === "win32" ? "bun.exe" : "bun"
-  for (const candidate of [p(root, "bin", name), p(home(), ".bun", "bin", name)]) {
+  for (const candidate of [p(root, "bin", "bun"), p(home(), ".bun", "bin", "bun")]) {
     const found = exec.which(candidate)
-    if (found !== "" && absoluteExecutable(found, platform)) return { command: found, path: found }
+    if (found !== "" && isAbsolute(found)) return { command: found, path: found }
   }
   return undefined
 }
 
-const resolveBun = (exec: ProbeExecutor, platform: NodeJS.Platform): ProbeResult => {
-  const bun = findBun(exec, platform)
+const resolveBun = (exec: ProbeExecutor): ProbeResult => {
+  const bun = findBun(exec)
   return bun === undefined
     ? { state: "missing" }
     : { state: "present", path: bun.path }
@@ -160,28 +156,23 @@ const versionEffectSolutions = (exec: ProbeExecutor): string => {
   return match?.[1] ?? ""
 }
 
-const locateEffectSolutions = (exec: ProbeExecutor, platform: NodeJS.Platform): DependencyLocation => {
-  const strictBun = findBun(exec, platform)
+const locateEffectSolutions = (exec: ProbeExecutor): DependencyLocation => {
+  const strictBun = findBun(exec)
   const pathBun = exec.which("bun")
   const bun = strictBun ?? (pathBun !== "" ? { command: "bun", path: pathBun } : undefined)
   if (bun === undefined) return { path: "", binDir: "" }
   const globalBin = exec.capture(bun.command, ["pm", "-g", "bin"])
-  const names =
-    platform === "win32"
-      ? ["effect-solutions.exe", "effect-solutions.cmd", "effect-solutions.bunx"]
-      : ["effect-solutions"]
-  const path = names.map((name) => p(globalBin, name)).find((candidate) => globalBin !== "" && exec.which(candidate) !== "")
-  return { path: path ?? "", binDir: globalBin }
+  const path = globalBin !== "" ? p(globalBin, "effect-solutions") : ""
+  const resolved = path !== "" && exec.which(path) !== "" ? path : ""
+  return { path: resolved, binDir: globalBin }
 }
 
 const resolveChrome = (exec: ProbeExecutor, platform: NodeJS.Platform): ProbeResult => {
   const root = p(home(), ".agent-browser", "browsers")
   const relative =
-    platform === "win32"
-      ? "chrome.exe"
-      : platform === "darwin"
-        ? "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
-        : "chrome"
+    platform === "darwin"
+      ? "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+      : "chrome"
   if (existsSync(root)) {
     for (const directory of readdirSync(root).filter((name) => name.startsWith("chrome-")).sort().reverse()) {
       const path = exec.which(p(root, directory, relative))
@@ -214,23 +205,19 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     "git",
     "optional",
     (pf = rawPlatform()) =>
-      pf === "win32"
-        ? "winget install Git.Git (then open a new terminal)"
-        : pf === "darwin"
-          ? "brew install git"
-          : "sudo apt install -y git (or your distro's package manager)",
+      pf === "darwin"
+        ? "brew install git"
+        : "sudo apt install -y git (or your distro's package manager)",
     { version: versionProbe("git") }
   ),
   jq: spec("jq", "optional", (pf = rawPlatform()) =>
-    pf === "win32"
-      ? "winget install jqlang.jq (then open a new terminal)"
-      : pf === "darwin"
-        ? "brew install jq"
-        : "sudo apt install -y jq",
+    pf === "darwin"
+      ? "brew install jq"
+      : "sudo apt install -y jq",
     { version: versionProbe("jq") }
   ),
   curl: spec("curl", "optional", (pf = rawPlatform()) =>
-    pf === "win32" ? "winget install cURL.cURL" : pf === "darwin" ? "brew install curl" : "sudo apt install -y curl",
+    pf === "darwin" ? "brew install curl" : "sudo apt install -y curl",
     { version: versionProbe("curl") }
   ),
   node: spec("node", "optional", () => "install Node.js via https://nodejs.org (or your package manager)", {
@@ -241,34 +228,32 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
   claude: spec(
     "claude",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "win32"
-        ? "winget install Anthropic.ClaudeCode"
-        : "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh",
+    () => "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh",
     { version: versionProbe("claude") }
   ),
   codex: spec(
     "codex",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "win32"
-        ? `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"`
-        : 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"',
+    () => 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"',
     { version: versionProbe("codex") }
   ),
-  rtk: spec("rtk", "optional", () => "see https://github.com/rtk-ai/rtk (kit auto-install is Unix-only)", {
+  rtk: spec("rtk", "optional", () => "see https://github.com/rtk-ai/rtk (kit auto-install is Linux/macOS-only)", {
     version: versionProbe("rtk"),
     latest: latestRtk
   }),
+  "session-relay": spec("session-relay", "optional", () => "docks-kit toolchain ensure session-relay", {
+    resolve: (exec) => pathProbe(p(home(), ".local", "bin", "session-relay"))(exec),
+    version: (exec) => exec.capture(p(home(), ".local", "bin", "session-relay"), ["--version"]),
+    locate: () => ({ path: p(home(), ".local", "bin", "session-relay"), binDir: p(home(), ".local", "bin") })
+  }),
   bun: spec(
     "bun",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "win32" ? `powershell -c "irm bun.sh/install.ps1 | iex"` : "curl -fsSL https://bun.sh/install | bash",
+    () => "curl -fsSL https://bun.sh/install | bash",
     {
       resolve: resolveBun,
       version: (exec) => exec.capture(versionBunCommand(exec), ["--version"]),
-      locate: (exec, platform) => ({ path: findBun(exec, platform)?.path ?? "", binDir: "" })
+      locate: (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
     }
   ),
   bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)"),
@@ -292,7 +277,7 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     "ffplay",
     "optional",
     (pf = rawPlatform()) =>
-      pf === "win32" ? "winget install Gyan.FFmpeg" : pf === "darwin" ? "brew install ffmpeg" : "sudo apt install -y ffmpeg",
+      pf === "darwin" ? "brew install ffmpeg" : "sudo apt install -y ffmpeg",
     { versionArgs: ["-version"], resolve: pathProbe("ffplay") }
   ),
   intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {

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

@@ -7,11 +7,7 @@ import { spawnSync } from "node:child_process"
 import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, isAbsolute, join } from "node:path"
 
-/**
- * Engine paths are built with "/" because they appear verbatim in output
- * (dry-run lines, warns), where node:path.join would print "\" on Windows
- * and break the golden contract. fs accepts "/" on every platform.
- */
+/** Keep engine paths slash-separated so rendered output is host-stable. */
 export function p(...parts: Array<string>): string {
   return parts.join("/")
 }
@@ -22,18 +18,15 @@ export function capture(cmd: string, args: ReadonlyArray<string>): string {
   return (res.stdout ?? "").replace(/[\r\n]+$/, "")
 }
 
-/** `command -v` — resolve a name on PATH (PATHEXT-aware on Windows). */
+/** `command -v` — resolve an executable name on PATH. */
 export function which(name: string): string {
-  if (isAbsolute(name) || name.includes("/") || name.includes("\\")) {
+  if (isAbsolute(name) || name.includes("/")) {
     return isExecutable(name) ? name : ""
   }
-  const exts = process.platform === "win32" ? (process.env["PATHEXT"] ?? ".EXE;.CMD;.BAT;.COM").split(";").concat("") : [""]
   for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
     if (dir === "") continue
-    for (const ext of exts) {
-      const cand = join(dir, name + ext.toLowerCase())
-      if (isExecutable(cand)) return cand
-    }
+    const candidate = join(dir, name)
+    if (isExecutable(candidate)) return candidate
   }
   return ""
 }
@@ -45,7 +38,7 @@ export function commandExists(name: string): boolean {
 export function isExecutable(p: string): boolean {
   try {
     if (!statSync(p).isFile()) return false
-    if (process.platform !== "win32") accessSync(p, constants.X_OK)
+    accessSync(p, constants.X_OK)
     return true
   } catch {
     return false

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

@@ -12,6 +12,7 @@ import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
 import { ensureRtk } from "./claudeSync"
+import { ensureSessionRelayCli } from "./sessionRelayCli"
 import { bunBootstrap } from "./bun"
 import { agentBrowserInstall, effectSolutionsInstall } from "./skillsSync"
 import { ensure, report } from "./toolchain"
@@ -142,8 +143,10 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
       return ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
     case "agent-browser":
       return ensure(ctx, "agent-browser", agentBrowserInstall)
+    case "session-relay":
+      return ensureSessionRelayCli(ctx)
     default:
-      err("toolchain ensure supports managed tools only (rtk, bun, effect-solutions, agent-browser)")
+      err("toolchain ensure supports managed tools only (rtk, bun, effect-solutions, agent-browser, session-relay)")
       return 2
   }
 }

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

@@ -1,29 +1,24 @@
 /**
- * Platform capability seam (Output Policy in DESIGN.md) — the only engine
- * module that reads process.platform besides exec.ts's PATH/executability
- * primitives. Per-tool package identifiers stay in deps.ts; symlink handling
- * stays try-then-fallback at the call site (capability-driven, not predicted).
+ * Platform capability seam (Output Policy in DESIGN.md). Per-tool package
+ * identifiers stay in deps.ts; symlink handling stays try-then-fallback at
+ * the call site (capability-driven, not predicted).
  */
 
-export type PlatformName = "linux" | "darwin" | "windows" | "unknown"
+export type PlatformName = "linux" | "darwin" | "unknown"
 
 export function rawPlatform(): NodeJS.Platform {
   return process.platform
 }
 
 export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName {
-  return pf === "linux" ? "linux" : pf === "darwin" ? "darwin" : pf === "win32" ? "windows" : "unknown"
-}
-
-export function isWindows(): boolean {
-  return rawPlatform() === "win32"
+  return pf === "linux" ? "linux" : pf === "darwin" ? "darwin" : "unknown"
 }
 
 export function isLinux(): boolean {
   return rawPlatform() === "linux"
 }
 
-/** Shell-rc exports (bashrc/zshrc) apply only off Windows. */
+/** Shell-rc exports apply only on supported hosts. */
 export function shellRcApplicable(): boolean {
-  return !isWindows()
+  return platformName() !== "unknown"
 }

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

@@ -36,7 +36,6 @@ export interface DependencyManager {
 export interface Platform {
   readonly raw: () => NodeJS.Platform
   readonly name: () => PlatformName
-  readonly isWindows: () => boolean
   readonly isLinux: () => boolean
   readonly shellRcApplicable: () => boolean
 }
@@ -51,13 +50,12 @@ export interface EngineServiceOptions {
   readonly sinks?: LoggerSinks
 }
 
-/** Platform view over an injectable platform id (tests pass e.g. "win32"). */
+/** Platform view over an injectable platform id. */
 export const makePlatform = (pf: NodeJS.Platform = rawPlatform()): Platform => ({
   raw: () => pf,
   name: () => platformName(pf),
-  isWindows: () => pf === "win32",
   isLinux: () => pf === "linux",
-  shellRcApplicable: () => pf !== "win32"
+  shellRcApplicable: () => pf === "linux" || pf === "darwin"
 })
 
 /** DependencyManager whose hints default to the INJECTED platform, not the host. */

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

@@ -0,0 +1,257 @@
+import { spawnSync } from "node:child_process"
+import { createHash, randomBytes } from "node:crypto"
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync
+} from "node:fs"
+import { dirname, join } from "node:path"
+
+import { isObject, parseJson, type Json } from "./jq"
+import type { Ctx } from "./index"
+import { ExitError } from "./parseArgs"
+import { payloadText } from "../payload"
+
+const VERSION = "0.12.0"
+const REPOSITORY = "DocksDocks/docks"
+const TAG = "session-relay--v0.12.0"
+const PLUGIN_ID = "session-relay@docks"
+const INSTALL_PATH = "~/.local/bin/session-relay"
+const TARGETS = [
+  "x86_64-unknown-linux-musl",
+  "aarch64-unknown-linux-musl",
+  "x86_64-apple-darwin",
+  "aarch64-apple-darwin"
+] as const
+
+export type SessionRelayTarget = typeof TARGETS[number]
+
+export interface SessionRelayManifest {
+  readonly kind: "managed-release"
+  readonly policy: "exact"
+  readonly verified: typeof VERSION
+  readonly repository: typeof REPOSITORY
+  readonly tag: typeof TAG
+  readonly plugin_id: typeof PLUGIN_ID
+  readonly plugin_version: typeof VERSION
+  readonly install_path: typeof INSTALL_PATH
+  readonly assets: Readonly<Record<SessionRelayTarget, string>>
+}
+
+export interface SessionRelayInstallOps {
+  readonly download: (url: string, destination: string) => boolean
+  readonly chmod: (path: string, mode: number) => void
+  readonly runVersion: (path: string) => { readonly ok: boolean; readonly stdout: string }
+  readonly rename: (from: string, to: string) => void
+  readonly uniqueSuffix: () => string
+}
+
+export interface SessionRelayInstallInput {
+  readonly home: string
+  readonly dryRun: boolean
+  readonly platform: string
+  readonly arch: string
+  readonly manifestText: string
+  readonly log: (line: string) => void
+  readonly error?: (line: string) => void
+}
+
+function fail(input: SessionRelayInstallInput, message: string): never {
+  input.error?.(message)
+  const error = new ExitError(1)
+  error.message = message
+  throw error
+}
+
+function exactKeys(value: { [key: string]: Json }, expected: ReadonlyArray<string>, label: string): void {
+  const actual = Object.keys(value).sort()
+  const wanted = [...expected].sort()
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw new Error(`${label} violates the closed Session Relay manifest schema`)
+  }
+}
+
+export function parseSessionRelayManifest(text: string): SessionRelayManifest {
+  const value = parseJson(text)
+  if (value === undefined || !isObject(value)) throw new Error("Session Relay manifest is not a JSON object")
+  exactKeys(
+    value,
+    ["kind", "policy", "verified", "repository", "tag", "plugin_id", "plugin_version", "install_path", "assets"],
+    "Session Relay manifest"
+  )
+  const expected = {
+    kind: "managed-release",
+    policy: "exact",
+    verified: VERSION,
+    repository: REPOSITORY,
+    tag: TAG,
+    plugin_id: PLUGIN_ID,
+    plugin_version: VERSION,
+    install_path: INSTALL_PATH
+  } as const
+  for (const [key, wanted] of Object.entries(expected)) {
+    if (value[key] !== wanted) throw new Error(`Session Relay manifest ${key.replaceAll("_", " ")} must be ${wanted}`)
+  }
+  const assets = value["assets"]
+  if (!isObject(assets)) throw new Error("Session Relay manifest assets must be an object")
+  exactKeys(assets, TARGETS, "Session Relay manifest assets target set")
+  const parsedAssets = {} as Record<SessionRelayTarget, string>
+  for (const target of TARGETS) {
+    const digest = assets[target]
+    if (typeof digest !== "string" || !/^[0-9a-f]{64}$/.test(digest)) {
+      throw new Error(`Session Relay manifest digest for ${target} must be 64 lowercase hex characters`)
+    }
+    parsedAssets[target] = digest
+  }
+  return { ...expected, assets: parsedAssets }
+}
+
+function manifestEntry(): string {
+  const document = parseJson(payloadText("SoT/toolchain.json"))
+  const tools = document !== undefined && isObject(document) ? document["tools"] : undefined
+  const entry = tools !== undefined && isObject(tools) ? tools["session-relay"] : undefined
+  if (entry === undefined) throw new Error("Embedded toolchain manifest has no session-relay entry")
+  return JSON.stringify(entry)
+}
+
+export function sessionRelayTarget(platform: string, arch: string): SessionRelayTarget {
+  if (platform === "linux" && arch === "x64") return "x86_64-unknown-linux-musl"
+  if (platform === "linux" && arch === "arm64") return "aarch64-unknown-linux-musl"
+  if (platform === "darwin" && arch === "x64") return "x86_64-apple-darwin"
+  if (platform === "darwin" && arch === "arm64") return "aarch64-apple-darwin"
+  throw new Error(`Unsupported host for Session Relay CLI: ${platform}/${arch}; supported: linux|darwin x64|arm64`)
+}
+
+function trimOneLineEnding(text: string): string {
+  if (text.endsWith("\r\n")) return text.slice(0, -2)
+  if (text.endsWith("\n")) return text.slice(0, -1)
+  return text
+}
+
+function exactVersion(ops: SessionRelayInstallOps, path: string): boolean {
+  const result = ops.runVersion(path)
+  return result.ok && trimOneLineEnding(result.stdout) === `session-relay ${VERSION}`
+}
+
+function selectedChecksum(text: string, assetName: string): string {
+  const selected = text.split("\n").filter((line) => line.endsWith(`  ${assetName}`))
+  if (selected.length !== 1 || !new RegExp(`^[0-9a-f]{64}  ${assetName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`).test(selected[0]!)) {
+    throw new Error(`SHA256SUMS must contain exactly one canonical row for ${assetName}`)
+  }
+  return selected[0]!.slice(0, 64)
+}
+
+const defaultOps: SessionRelayInstallOps = {
+  download: (url, destination) => {
+    const result = spawnSync("curl", ["-fL", "--retry", "2", "--connect-timeout", "10", "--output", destination, url], {
+      stdio: "inherit"
+    })
+    return result.error === undefined && result.status === 0
+  },
+  chmod: chmodSync,
+  runVersion: (path) => {
+    const result = spawnSync(path, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+    return { ok: result.error === undefined && result.status === 0, stdout: result.stdout ?? "" }
+  },
+  rename: renameSync,
+  uniqueSuffix: () => `${process.pid}-${randomBytes(8).toString("hex")}`
+}
+
+export function installSessionRelayCli(
+  input: SessionRelayInstallInput,
+  ops: SessionRelayInstallOps = defaultOps
+): void {
+  let manifest: SessionRelayManifest
+  let target: SessionRelayTarget
+  try {
+    manifest = parseSessionRelayManifest(input.manifestText)
+    target = sessionRelayTarget(input.platform, input.arch)
+  } catch (error) {
+    fail(input, error instanceof Error ? error.message : String(error))
+  }
+
+  if (input.dryRun) {
+    input.log(
+      `[dry-run] ensure Session Relay CLI ${manifest.verified} from ${manifest.repository}@${manifest.tag} (${target}) -> ${manifest.install_path}`
+    )
+    return
+  }
+
+  const stable = join(input.home, ".local", "bin", "session-relay")
+  if (existsSync(stable) && exactVersion(ops, stable)) return
+
+  const parent = dirname(stable)
+  try {
+    mkdirSync(parent, { recursive: true, mode: 0o755 })
+    if (!statSync(parent).isDirectory()) {
+      fail(input, `Session Relay install parent is not a directory: ${parent}`)
+    }
+  } catch (error) {
+    if (error instanceof ExitError) throw error
+    fail(input, `Cannot prepare Session Relay install directory ${parent}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  const suffix = ops.uniqueSuffix()
+  const stage = join(parent, `.session-relay.stage-${suffix}`)
+  const checksumFile = join(parent, `.session-relay.checksums-${suffix}`)
+  const assetName = `session-relay-${target}`
+  const baseUrl = `https://github.com/${manifest.repository}/releases/download/${manifest.tag}`
+
+  try {
+    if (!ops.download(`${baseUrl}/${assetName}`, stage)) fail(input, `Failed to download pinned Session Relay asset ${assetName}`)
+    if (!ops.download(`${baseUrl}/SHA256SUMS`, checksumFile)) fail(input, "Failed to download pinned Session Relay SHA256SUMS")
+
+    let checksumDigest: string
+    try {
+      checksumDigest = selectedChecksum(readFileSync(checksumFile, "utf8"), assetName)
+    } catch (error) {
+      fail(input, error instanceof Error ? error.message : String(error))
+    }
+    const sourceDigest = manifest.assets[target]
+    if (checksumDigest !== sourceDigest) fail(input, `Session Relay source pin does not match SHA256SUMS for ${assetName}`)
+    const downloadedDigest = createHash("sha256").update(readFileSync(stage)).digest("hex")
+    if (downloadedDigest !== sourceDigest) fail(input, `Downloaded Session Relay checksum mismatch for ${assetName}`)
+
+    try {
+      ops.chmod(stage, 0o755)
+    } catch (error) {
+      fail(input, `Failed to chmod staged Session Relay CLI: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (!exactVersion(ops, stage)) fail(input, `Staged Session Relay CLI did not report exact version session-relay ${VERSION}`)
+    try {
+      ops.rename(stage, stable)
+    } catch (error) {
+      fail(input, `Failed to atomically replace Session Relay CLI: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    input.log(`Session Relay CLI ready (${VERSION})`)
+  } finally {
+    try {
+      rmSync(stage, { force: true })
+    } catch {
+      // A cleanup failure must not turn a successful atomic replacement into
+      // an install failure or alter a pre-existing stable executable.
+    }
+    try {
+      rmSync(checksumFile, { force: true })
+    } catch {
+      // Same failure-preservation rule as the staged executable above.
+    }
+  }
+}
+
+export function ensureSessionRelayCli(ctx: Ctx): number {
+  installSessionRelayCli({
+    home: ctx.home,
+    dryRun: ctx.dryRun,
+    platform: ctx.services.platform.raw(),
+    arch: process.arch,
+    manifestText: manifestEntry(),
+    log: ctx.dryRun ? ctx.services.logger.echo : ctx.services.logger.change,
+    error: ctx.services.logger.err
+  })
+  return 0
+}