@huynle/hub 0.7.1 → 0.7.2

package/src/central/store.ts

@@ -58,6 +58,9 @@ export interface ViewPrefs {
 }
 
 export const VIEW_PREF_KEYS = ["hiddenSessions", "hiddenWorkspaces", "pinnedSessions", "pinnedWorkspaces"] as const
+/** Archived sessions accumulate for longer than the other view-preference lists. */
+export const VIEW_PREF_MAX_ARCHIVED = 5000
+export const VIEW_PREF_MAX_PINNED = 500
 
 export interface AuditEntry {
   at: number
@@ -911,6 +914,56 @@ export class Store {
     })
   }
 
+  /** Changes one archived session atomically; undefined means the bounded archive list is full. */
+  setSessionArchived(id: string, sessionID: string, archived: boolean): Promise<{ changed: boolean } | undefined> {
+    return this.mutate((tx) => {
+      const user = this.user(id)
+      if (!user) return undefined
+      const next = this.viewPrefs(id)
+      const listed = next.hiddenSessions.includes(sessionID)
+      const changed = archived !== listed
+      if (!changed) return { changed }
+      if (archived && next.hiddenSessions.length >= VIEW_PREF_MAX_ARCHIVED) return undefined
+      next.hiddenSessions = archived ? [...next.hiddenSessions, sessionID] : next.hiddenSessions.filter((id) => id !== sessionID)
+      user.viewPrefs = next
+      tx.touch("users", id)
+      return { changed }
+    })
+  }
+
+  /** Changes one pinned session atomically while preserving every other preference list. */
+  setSessionPinned(id: string, sessionID: string, pinned: boolean): Promise<{ changed: boolean } | undefined> {
+    return this.mutate((tx) => {
+      const user = this.user(id)
+      if (!user) return undefined
+      const next = this.viewPrefs(id)
+      const listed = next.pinnedSessions.includes(sessionID)
+      const changed = pinned !== listed
+      if (!changed) return { changed }
+      if (pinned && next.pinnedSessions.length >= VIEW_PREF_MAX_PINNED) return undefined
+      next.pinnedSessions = pinned ? [...next.pinnedSessions, sessionID] : next.pinnedSessions.filter((id) => id !== sessionID)
+      user.viewPrefs = next
+      tx.touch("users", id)
+      return { changed }
+    })
+  }
+
+  /** Archives only while still unpinned, atomically against concurrent preference writes. */
+  archiveSessionIfUnpinned(id: string, sessionID: string): Promise<"changed" | "pinned" | "archived" | "full" | "not_found"> {
+    return this.mutate((tx) => {
+      const user = this.user(id)
+      if (!user) return "not_found"
+      const next = this.viewPrefs(id)
+      if (next.hiddenSessions.includes(sessionID)) return "archived"
+      if (next.pinnedSessions.includes(sessionID)) return "pinned"
+      if (next.hiddenSessions.length >= VIEW_PREF_MAX_ARCHIVED) return "full"
+      next.hiddenSessions = [...next.hiddenSessions, sessionID]
+      user.viewPrefs = next
+      tx.touch("users", id)
+      return "changed"
+    })
+  }
+
   // ---------- per-user, per-session model preferences ----------
 
   modelPrefs(id: string, sessionID: string): SessionModelPrefs {

package/src/config.ts

@@ -1,6 +1,7 @@
 // Per-machine spoke configuration, shared by every OpenCode process on the machine and edited
 // from the /hub dialog. Holds the machine token, so it is written with mode 0600.
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { randomBytes } from "node:crypto"
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { hubEnv, type Env } from "./env"
@@ -142,13 +143,75 @@ export function readConfig(file: string, machineName: string): VoiceConfig {
   }
 }
 
-/** Atomic write with 0600 permissions. */
-export function writeConfig(file: string, config: VoiceConfig): void {
+/** The keys VoiceConfig owns in config.json; every other key belongs to someone else and is preserved. */
+const CONFIG_KEYS = ["server", "mode", "sessions", "machineName", "subagent", "autoStartLocalHub", "herdr", "list", "voiceModel", "workModel", "machineID", "token"] as const satisfies readonly (keyof VoiceConfig)[]
+
+type RawConfig = Record<string, unknown>
+
+const isObject = (v: unknown): v is RawConfig => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** The raw JSON object in `file` (every key, known or not); undefined when the file does not exist. */
+export function readRawConfig(file: string): RawConfig | undefined {
+  let text: string
+  try {
+    text = readFileSync(file, "utf8")
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return undefined
+    throw cause
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    parsed = undefined
+  }
+  if (!isObject(parsed)) throw new Error(`${file} is not a JSON object; fix or remove it first`)
+  return parsed
+}
+
+/** Writes `content` to `file` atomically (a private temp file in the same directory, fsync, rename), mode 0600. */
+function writePrivate(file: string, content: string): void {
   mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
-  const tmp = `${file}.${process.pid}.tmp`
-  writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
-  chmodSync(tmp, 0o600)
-  renameSync(tmp, file)
+  const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`
+  let fd: number | undefined
+  try {
+    fd = openSync(tmp, "wx", 0o600)
+    writeSync(fd, content)
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = undefined
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, file)
+  } catch (cause) {
+    if (fd !== undefined) closeSync(fd)
+    rmSync(tmp, { force: true })
+    throw cause
+  }
+}
+
+const serialize = (raw: RawConfig) => `${JSON.stringify(raw, null, 2)}\n`
+
+/**
+ * Lossless read-modify-write of config.json: `update` gets the raw object (every key, {} for a missing file) and
+ * returns the next one, written atomically with 0600. Refuses (throws, file untouched) when the file is not a JSON
+ * object, so a hand-edited config is never replaced.
+ */
+export function updateRawConfig(file: string, update: (raw: RawConfig) => RawConfig): void {
+  writePrivate(file, serialize(update(readRawConfig(file) ?? {})))
+}
+
+/**
+ * Atomic write with 0600 permissions. Lossless: keys config.json holds that VoiceConfig does not know are kept; the
+ * known keys come from `config` (a known key it lacks is removed). A file that is not a JSON object is replaced.
+ */
+export function writeConfig(file: string, config: VoiceConfig): void {
+  let previous: RawConfig = {}
+  try {
+    previous = readRawConfig(file) ?? {}
+  } catch {}
+  const next: RawConfig = { ...previous }
+  for (const key of CONFIG_KEYS) delete next[key]
+  writePrivate(file, serialize({ ...next, ...config }))
 }
 
 /** Changing the server URL drops the machine credentials, which belong to the old server. */

package/src/index.ts

@@ -2,9 +2,10 @@
 // console, phones and (optional) Voice speech live on the hub; this side only exposes sessions, forwards
 // their events, and runs remote / voice turns and permission replies on request.
 import { mkdirSync, readFileSync } from "node:fs"
-import { hostname } from "node:os"
+import { homedir, hostname } from "node:os"
 import { fileURLToPath } from "node:url"
-import { Plugin } from "@opencode/plugin"
+// Types only: @opencode/plugin's runtime entry loads its whole schema graph (~1 s cold) for an identity define().
+import type { Plugin } from "@opencode/plugin"
 import { DEFAULT_SUBAGENT, prepareConfigPath } from "./config"
 import { HubRpc, VoiceRpc } from "./rpc"
 import { jobFromInfo, type JobInfo } from "./protocol"
@@ -15,7 +16,7 @@ import { herdrRunner } from "./spoke/herdr"
 import { launchSource } from "./spoke/launch-source"
 import { HubRpcError, hubMsg, hubWho } from "./spoke/hub-rpc"
 import { HUB_TOOL, HUB_TOOL_DESCRIPTION, HUB_TOOL_INPUT, runHubTool } from "./spoke/hub-tool"
-import { cliEntry, installLaunchers } from "./spoke/launchers"
+import { cliEntry, installLaunchers, linkUserBin, standaloneHubctl } from "./spoke/launchers"
 import { listServiceSessions } from "./spoke/listing"
 import { ensureLocalHub } from "./spoke/localhub"
 import { nodeConfigPath, readWorkspaceRoots } from "./spoke/node-roots"
@@ -27,6 +28,18 @@ import { detectKind, Spoke, SpokeError, type FormAction, type SpokeHost } from "
 
 type Context = Parameters<Parameters<typeof Plugin.define>[0]["setup"]>[0]
 
+/** Plugin.define without importing it (it returns its argument). */
+const definePlugin = (plugin: Plugin.Plugin): Plugin.Plugin => plugin
+
+/** One registration with OpenCode; a failure is logged and never stops the others. */
+async function attempt(what: string, register: () => Promise<unknown> | undefined): Promise<void> {
+  try {
+    await register()
+  } catch (cause) {
+    console.error(`[hub] could not ${what}`, cause)
+  }
+}
+
 const VOICE_STYLE =
   "This message came from a voice conversation and your reply will be read aloud. " +
   "Answer in at most three short sentences of plain speech: no markdown, code blocks, tables, or lists. " +
@@ -199,25 +212,29 @@ async function registerShellEnv(ctx: Context, identity: (sessionID: string) => {
     // The `hub`/`hubctl` launchers run the CLI with this runtime (OpenCode's binary as bun; src/spoke/launchers.ts).
     const bun = typeof process.versions.bun === "string"
     const entry = cliEntry(fileURLToPath(new URL("..", import.meta.url)), bun)
-    if (entry) installLaunchers({ binDir, execPath: process.execPath, bun, entry })
-    else console.error("[hub] no built hub CLI (packages/cli/dist/hub-cli.js): `hub` is not installed")
+    if (entry) {
+      installLaunchers({ binDir, execPath: process.execPath, bun, entry, standalone: standaloneHubctl(homedir()) })
+      // `hub` in the user's own terminals too (~/.local/bin/hub, never over anything of theirs).
+      const { hint } = linkUserBin({ home: homedir(), binDir, path: process.env.PATH })
+      if (hint) console.error(`[hub] ${hint}`)
+    } else console.error("[hub] no built hub CLI (packages/cli/dist/hub-cli.js): `hub` is not installed")
   } catch (cause) {
     console.error("[hub] could not install the hub CLI launchers", cause)
   }
   const injector = envInjector({ correlator: new ShellCorrelator(), binDir, identity })
   const tool = (ctx as any).tool
   const shell = (ctx as any).shell
-  try {
+  await attempt("register the shell environment hooks", async () => {
     if (!tool?.hook || !shell?.hook) throw new Error("this OpenCode has no tool/shell hooks")
-    await tool.hook("execute.before", (event: any) => injector.toolBefore(event))
-    await tool.hook("execute.after", (event: any) => injector.toolAfter(event))
-    await shell.hook("create.before", (invocation: any) => injector.shellBefore(invocation))
-  } catch (cause) {
-    console.error("[hub] could not register the shell environment hooks", cause)
-  }
+    await Promise.all([
+      tool.hook("execute.before", (event: any) => injector.toolBefore(event)),
+      tool.hook("execute.after", (event: any) => injector.toolAfter(event)),
+      shell.hook("create.before", (invocation: any) => injector.shellBefore(invocation)),
+    ])
+  })
 }
 
-export default Plugin.define({
+export default definePlugin({
   id: "hub",
   async setup(ctx) {
     // An OpenCode started from a session's shell must not act as that session (nor hand its token to its shells).
@@ -249,82 +266,69 @@ export default Plugin.define({
       permissionLocation(ctx),
     )
 
-    try {
-      await ctx.agent.transform((editor) => defineVoiceAgent(editor as any))
-    } catch (cause) {
-      console.error("[hub] could not register the voice agent", cause)
-    }
-
-    try {
-      await ctx.session.hook("context", (event) => {
-        const spoke = membership.active()
-        if (spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
-        const parts = orchestratorParts({
-          agent: event.agent,
-          conversation: spoke?.inConversation(event.sessionID) ?? false,
-          subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
-          workModel: spoke?.workModelFor(event.sessionID),
-          taskBoard: spoke?.taskBoard(event.sessionID),
-        })
-        for (const text of parts) event.system.push({ type: "text", text })
-      })
-    } catch (cause) {
-      console.error("[hub] could not register the context hook", cause)
-    }
-
-    try {
+    // Every registration is independent: they run together, so OpenCode's plugin activation (bounded at ~5 s on a
+    // cold start) waits for about one of them, not their sum.
+    const registrations: Promise<void>[] = [
+      attempt("register the voice agent", () => ctx.agent.transform((editor) => defineVoiceAgent(editor as any))),
+      attempt("register the context hook", () =>
+        ctx.session.hook("context", (event) => {
+          const spoke = membership.active()
+          if (spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
+          const parts = orchestratorParts({
+            agent: event.agent,
+            conversation: spoke?.inConversation(event.sessionID) ?? false,
+            subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
+            workModel: spoke?.workModelFor(event.sessionID),
+            taskBoard: spoke?.taskBoard(event.sessionID),
+          })
+          for (const text of parts) event.system.push({ type: "text", text })
+        }),
+      ),
       // The voice agent stops one worker ("cancel the deploy one") without stopping itself or the others.
-      await (ctx as any).tool?.transform?.((editor: any) =>
-        editor.add({
-          name: STOP_TOOL,
-          description: STOP_TOOL_DESCRIPTION,
-          input: {
-            type: "object",
-            properties: {
-              sessionID: { type: "string", description: "The worker's sessionID, from your task board or the subagent tool's result." },
-              all: { type: "boolean", description: "true: stop every worker of yours that is still running." },
+      attempt("register the task stop tool", () =>
+        (ctx as any).tool?.transform?.((editor: any) =>
+          editor.add({
+            name: STOP_TOOL,
+            description: STOP_TOOL_DESCRIPTION,
+            input: {
+              type: "object",
+              properties: {
+                sessionID: { type: "string", description: "The worker's sessionID, from your task board or the subagent tool's result." },
+                all: { type: "boolean", description: "true: stop every worker of yours that is still running." },
+              },
+              additionalProperties: false,
             },
-            additionalProperties: false,
-          },
-          options: { codemode: false },
-          execute: async (value: unknown, context: { sessionID: string }) => {
-            const spoke = membership.active()
-            if (!spoke) return { content: "The hub is not running in this OpenCode process; nothing was stopped." }
-            const { stopped, text } = await spoke.stopWorkers(context.sessionID, (value ?? {}) as Record<string, unknown>)
-            return { content: text, metadata: { stopped } }
-          },
-        }),
-      )
-    } catch (cause) {
-      console.error("[hub] could not register the task stop tool", cause)
-    }
-
-    try {
+            options: { codemode: false },
+            execute: async (value: unknown, context: { sessionID: string }) => {
+              const spoke = membership.active()
+              if (!spoke) return { content: "The hub is not running in this OpenCode process; nothing was stopped." }
+              const { stopped, text } = await spoke.stopWorkers(context.sessionID, (value ?? {}) as Record<string, unknown>)
+              return { content: text, metadata: { stopped } }
+            },
+          }),
+        ),
+      ),
       // Agents message and ask other sessions as themselves (the session's own hub token; src/spoke/hub-tool.ts).
-      await (ctx as any).tool?.transform?.((editor: any) =>
-        editor.add({
-          name: HUB_TOOL,
-          description: HUB_TOOL_DESCRIPTION,
-          input: HUB_TOOL_INPUT,
-          options: { codemode: false },
-          execute: (value: unknown, context: { sessionID: string; signal?: AbortSignal }) =>
-            runHubTool(() => membership.active(), value, { sessionID: context.sessionID, ...(context.signal ? { signal: context.signal } : {}) }),
-        }),
-      )
-    } catch (cause) {
-      console.error("[hub] could not register the hub tool", cause)
-    }
-
-    try {
+      attempt("register the hub tool", () =>
+        (ctx as any).tool?.transform?.((editor: any) =>
+          editor.add({
+            name: HUB_TOOL,
+            description: HUB_TOOL_DESCRIPTION,
+            input: HUB_TOOL_INPUT,
+            options: { codemode: false },
+            execute: (value: unknown, context: { sessionID: string; signal?: AbortSignal }) =>
+              runHubTool(() => membership.active(), value, { sessionID: context.sessionID, ...(context.signal ? { signal: context.signal } : {}) }),
+          }),
+        ),
+      ),
       // @name / @@role in a prompt get context from the hub as an attached text file; the text is never changed
       // and the harness's own @ meanings win (src/spoke/prompt-refs.ts, design §2.4).
-      const references = new PromptReferences(() => membership.active())
-      await ctx.session.hook("prompt", (event) => references.onPrompt(event))
-    } catch (cause) {
-      console.error("[hub] could not register the prompt hook", cause)
-    }
-
-    await registerShellEnv(ctx, (sessionID) => membership.active()?.shellIdentity(sessionID))
+      attempt("register the prompt hook", () => {
+        const references = new PromptReferences(() => membership.active())
+        return ctx.session.hook("prompt", (event) => references.onPrompt(event))
+      }),
+      registerShellEnv(ctx, (sessionID) => membership.active()?.shellIdentity(sessionID)),
+    ]
 
     const run = async <T>(rpc: { error: (...args: any[]) => any }, action: (spoke: Spoke) => T | Promise<T>) => {
       const spoke = membership.active()
@@ -376,13 +380,8 @@ export default Plugin.define({
       hubMsg: (value, rpc) => run(rpc, (s) => hubMsg(s, value)),
     } satisfies Parameters<typeof ctx.rpc.register<typeof HubRpc>>[1]
     // "hub", plus the opencode-voice id "voice" for clients built against the old name (see src/rpc.ts).
-    for (const definition of [HubRpc, VoiceRpc]) {
-      try {
-        await ctx.rpc.register(definition, handlers)
-      } catch (cause) {
-        console.error(`[hub] could not register RPC methods (${definition.id})`, cause)
-      }
-    }
+    for (const definition of [HubRpc, VoiceRpc]) registrations.push(attempt(`register RPC methods (${definition.id})`, () => ctx.rpc.register(definition, handlers)))
+    await Promise.all(registrations)
 
     return () => membership.leave()
   },

package/src/spoke/launchers.ts

@@ -3,8 +3,19 @@
 // bundle shipped in this package with the runtime running the plugin: OpenCode is a Bun-compiled binary that acts
 // as bun under BUN_BE_BUN=1, so no `bun` (or node) needs to be on PATH. Without Bun the bundle runs on `node`.
 // The CLI deletes BUN_BE_BUN from its own env at start, so nothing it starts inherits it.
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+//
+// A standalone hubctl at user-bin:hubctl (~/.local/bin/hubctl, what `hubctl setup` installs) wins: the launchers exec
+// it when it is there (checked at run time), so shells, services and MCP clients all run that one stable authority
+// rather than the bundle in the plugin's install (cache) directory.
+//
+// For the user's own terminals (a plugin-only install, where `hubctl setup` never ran), linkUserBin links
+// ~/.local/bin/hub to the `hub` launcher under the setup's user-bin rule (packages/cli/src/setup/user-bin.ts): only
+// when nothing is there or it is hub's own link, and never when another `hub` is on PATH. ~/.local/bin/hubctl is left
+// to `hubctl setup`: it is the standalone hubctl's install path (a link there would make that install refuse to write
+// through it, and the launchers would exec themselves).
+import { accessSync, chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs"
 import path from "node:path"
+import { userBinLinkDecision, type UserBinEntry } from "../../packages/cli/src/setup/user-bin.ts"
 
 export const LAUNCHERS = ["hub", "hubctl"] as const
 
@@ -20,14 +31,22 @@ export interface LauncherOptions {
   readonly bun: boolean
   /** The CLI entry the runtime runs. */
   readonly entry: string
+  /** The standalone hubctl to prefer when it exists (standaloneHubctl(home)). */
+  readonly standalone?: string
 }
 
+/** Where `hubctl setup` installs the standalone hubctl (contract user-bin:hubctl). */
+export const standaloneHubctl = (home: string): string => path.join(home, ".local", "bin", "hubctl")
+
 /** A word quoted for sh. */
 const quote = (word: string) => `'${word.replaceAll("'", `'\\''`)}'`
 
-export function launcherScript({ execPath, bun, entry }: LauncherOptions): string {
+const LAUNCHER_HEADER = "#!/bin/sh\n# hub CLI launcher"
+
+export function launcherScript({ execPath, bun, entry, standalone }: LauncherOptions): string {
   const command = bun ? `exec env BUN_BE_BUN=1 ${quote(execPath)} ${quote(entry)} "$@"` : `exec node ${quote(entry)} "$@"`
-  return `#!/bin/sh\n# hub CLI launcher, written by the hub OpenCode plugin at start (edits are overwritten).\n${command}\n`
+  const prefer = standalone ? `if [ -x ${quote(standalone)} ]; then exec ${quote(standalone)} "$@"; fi\n` : ""
+  return `${LAUNCHER_HEADER}, written by the hub OpenCode plugin at start (edits are overwritten).\n${prefer}${command}\n`
 }
 
 /** The entry to run from the package at `root`: the bundle, else (Bun only) the TypeScript source. */
@@ -66,3 +85,90 @@ export function installLaunchers(options: LauncherOptions & { readonly binDir: s
   }
   return { written }
 }
+
+/** The user's own bin dir (contract root user-bin). */
+export const userBinDir = (home: string): string => path.join(home, ".local", "bin")
+
+function entryOf(file: string): UserBinEntry {
+  try {
+    const info = lstatSync(file)
+    return info.isSymbolicLink() ? "symlink" : info.isFile() ? "file" : info.isDirectory() ? "directory" : "other"
+  } catch {
+    return "missing"
+  }
+}
+
+/** A file that starts like the launchers hub writes. */
+function isLauncher(file: string): boolean {
+  let fd: number | undefined
+  try {
+    fd = openSync(file, "r")
+    const buffer = Buffer.alloc(LAUNCHER_HEADER.length)
+    return readSync(fd, buffer, 0, buffer.length, 0) === buffer.length && buffer.toString("utf8") === LAUNCHER_HEADER
+  } catch {
+    return false
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+/** The first executable `name` on `searchPath`, outside `skip`, as found (not followed). */
+function onPath(name: string, searchPath: string, skip: string): string | undefined {
+  for (const dir of searchPath.split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir) || path.resolve(dir) === path.resolve(skip)) continue
+    const file = path.join(dir, name)
+    try {
+      if (!statSync(file).isFile()) continue
+      accessSync(file, constants.X_OK)
+      return file
+    } catch {}
+  }
+  return undefined
+}
+
+/**
+ * Links ~/.local/bin/hub to `binDir`/hub (see the header). Returns what it linked, and one hint when the user's
+ * terminal will not find it (~/.local/bin not on `path`, or another `hub` comes first). Small synchronous calls,
+ * nothing when converged (the plugin runs this at start).
+ */
+export function linkUserBin(options: { readonly home: string; readonly binDir: string; readonly path: string | undefined }): { linked: string[]; hint?: string } {
+  // Only the default hub bin dir (~/.local/state/hub/bin): a custom HUB_STATE_DIR (tests, containers, a throwaway
+  // state) must never leave ~/.local/bin pointing into it.
+  if (path.resolve(options.binDir) !== path.join(options.home, ".local", "state", "hub", "bin")) return { linked: [] }
+  const userBin = userBinDir(options.home)
+  const linkPath = path.join(userBin, "hub")
+  const target = path.join(options.binDir, "hub")
+  const entry = entryOf(linkPath)
+  let pointsTo: string | undefined
+  if (entry === "symlink") {
+    try {
+      pointsTo = path.resolve(userBin, readlinkSync(linkPath))
+    } catch {}
+  }
+  const searchPath = options.path ?? ""
+  const onUserPath = searchPath.split(path.delimiter).some((dir) => dir && path.resolve(dir) === path.resolve(userBin))
+  const pathHint = onUserPath ? undefined : `${userBin} is not on PATH: add it to use \`hub\` in your terminal (export PATH="$HOME/.local/bin:$PATH")`
+  // `hubctl setup` linked hub to the standalone hubctl: that is the better hub, keep it.
+  if (pointsTo === standaloneHubctl(options.home)) return { linked: [], ...(pathHint ? { hint: pathHint } : {}) }
+  const foundOnPath = onPath("hub", searchPath, options.binDir)
+  const decision = userBinLinkDecision({ entry, ...(pointsTo !== undefined ? { pointsTo } : {}), target, linkPath, hubOwned: isLauncher, ...(foundOnPath !== undefined ? { foundOnPath } : {}) })
+  if (decision === "foreign") return { linked: [] }
+  if (decision === "shadowed") return { linked: [], hint: `\`hub\` on your PATH is ${foundOnPath}, not hub's CLI; hub's is ${target}` }
+  if (decision === "in-place") return { linked: [], ...(pathHint ? { hint: pathHint } : {}) }
+  mkdirSync(userBin, { recursive: true, mode: 0o755 })
+  // A new link never replaces what may have appeared meanwhile (EEXIST); hub's own is re-pointed atomically.
+  if (decision === "create") {
+    symlinkSync(target, linkPath)
+    return { linked: ["hub"], ...(pathHint ? { hint: pathHint } : {}) }
+  }
+  const tmp = `${linkPath}.${process.pid}.tmp`
+  rmSync(tmp, { force: true })
+  symlinkSync(target, tmp)
+  try {
+    renameSync(tmp, linkPath)
+  } catch (cause) {
+    rmSync(tmp, { force: true })
+    throw cause
+  }
+  return { linked: ["hub"], ...(pathHint ? { hint: pathHint } : {}) }
+}