@geohar/pi-cribsheet 0.0.0

package/src/index.ts

@@ -0,0 +1,319 @@
+// Pi extension: run the `crib` (cribsheet) memory + code-index MCP server via the
+// `sharedserver` CLI, inject the reach-for-crib directive into the system prompt, and
+// ship the `/crib` recall command.
+//
+// It is the Pi counterpart of cribsheet's Claude Code and OpenCode plugins, and mirrors
+// their behaviour:
+//
+//   1. Stand-down switch — if a combiner already serves crib (global MCP_COMBINER, or
+//      the per-backend MCP_COMBINER_SERVES_CRIBSHEET override, which wins), do NOT
+//      launch a standalone backend. The combiner owns crib's lifecycle. Only the launch
+//      is gated — the directive and /crib command apply either way, since crib's tools
+//      are present via the combiner too.
+//   2. Process — on `session_start`, drive `sharedserver use … -- crib --mcp --http …`
+//      so one warm crib is running and refcounted (shared across clients). Released on
+//      `session_shutdown` when `reason === "quit"` (reload/resume/fork keep the process
+//      and re-attach).
+//   3. Directive — append the reach-for-crib text to the system prompt via
+//      `before_agent_start` (analogue of Claude Code's SessionStart additionalContext
+//      and OpenCode's system.transform).
+//   4. /crib command — a Pi command mirroring commands/crib.md: shells out to the crib
+//      CLI (`note apropos` + `code lookup`) and steers the model to summarise.
+//
+// MCP registration itself (pointing pi-mcp-adapter at crib) is a single mcp.json entry
+// — see mcp.json.example and the README; static, and unnecessary when combiner-served.
+// The sharedserver resolution is ported faithfully from plugins/opencode/src/index.ts.
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import type {
+    AutocompleteItem,
+    ExtensionAPI,
+    ExtensionCommandContext,
+    ExtensionContext,
+    SessionShutdownEvent,
+} from "./pi.js"
+import { resolveSharedserver } from "./sharedserver-resolve.js"
+
+const DEFAULT_PORT = 7732
+const DEFAULT_HOST = "127.0.0.1"
+const DEFAULT_NAME = "cribsheet"
+const DEFAULT_GRACE = "1h"
+// Floor-only against sharedserver's latest release: cribsheet consumes sharedserver
+// rather than shipping it. Kept equal to the sibling plugins' value.
+const SHAREDSERVER_MIN_VERSION = "0.6.7"
+
+type LogFn = (level: "info" | "warn" | "error", message: string) => void
+
+// ── the reach-for-crib directive ───────────────────────────────────
+// Appended to the system prompt so the agent reaches for crib's tools. Canonical
+// source: CLAUDE.md.example at the repo root; a release-time `prepack` copies it to this
+// package's root as instructions.txt (see package.json). A dev/unbuilt run without the
+// copy falls back to empty and simply injects nothing.
+const CRIB_DIRECTIVE: string = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url))
+        return readFileSync(join(here, "..", "instructions.txt"), "utf8")
+    } catch {
+        return ""
+    }
+})()
+const DIRECTIVE_MARKER = CRIB_DIRECTIVE.split("\n", 1)[0] ?? ""
+
+// ── env configuration ──────────────────────────────────────────────
+// The PI_CRIBSHEET_* namespace mirrors the OpenCode plugin's OPENCODE_CRIBSHEET_* and
+// the CC hook's CRIBSHEET_* set — one namespace per client.
+
+function env(name: string): string | undefined {
+    const v = process.env[name]
+    return v !== undefined && v !== "" ? v : undefined
+}
+
+function splitArgs(value: string | undefined): string[] {
+    if (!value) return []
+    return value.split(/\s+/).filter((s) => s.length > 0)
+}
+
+// ── stand-down switch (mirrors the CC hook's combiner_serves) ──────
+
+function truthy(v: string | undefined): boolean {
+    if (v == null) return false
+    return !["", "0", "false", "no", "off"].includes(v.trim().toLowerCase())
+}
+
+/** Does a combiner serve `name`? The per-backend `MCP_COMBINER_SERVES_<NAME>` override
+ *  wins over the global `MCP_COMBINER` switch (presence, even empty, counts). These are
+ *  the cross-tool switches shared with the CC/OpenCode plugins — NOT PI_-namespaced. */
+function combinerServes(name: string): boolean {
+    const key = "MCP_COMBINER_SERVES_" + name.toUpperCase().replace(/[-\s]/g, "_")
+    if (key in process.env) return truthy(process.env[key])
+    return truthy(process.env.MCP_COMBINER)
+}
+
+// ── crib command resolution (mirrors the OpenCode plugin) ──────────
+
+type Command = { cmd: string; args: string[] }
+
+function onPath(cmd: string): boolean {
+    return spawnSync(cmd, ["--version"], { stdio: "ignore", env: process.env }).status === 0
+}
+
+/** Resolve how to invoke crib: env command → `crib` on PATH → `uv run --project
+ *  <checkout> crib`. Returns the base command; callers append their own args. */
+function resolveCrib(): Command | undefined {
+    const command = env("PI_CRIBSHEET_COMMAND")
+    if (command) return { cmd: command, args: splitArgs(env("PI_CRIBSHEET_ARGS")) }
+    if (onPath("crib")) return { cmd: "crib", args: [] }
+    const checkout = env("PI_CRIBSHEET_CHECKOUT")
+    if (checkout && existsSync(checkout) && onPath("uv")) {
+        return { cmd: "uv", args: ["run", "--project", checkout, "crib"] }
+    }
+    return undefined
+}
+
+// ── sharedserver lifecycle ─────────────────────────────────────────
+
+type Attachment = { binary: string; name: string }
+let attachment: Attachment | null = null
+let cleanupInstalled = false
+
+function installProcessCleanup() {
+    if (cleanupInstalled) return
+    cleanupInstalled = true
+    process.on("exit", () => detach())
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as NodeJS.Signals[]) {
+        process.on(sig, () => {
+            detach()
+            process.kill(process.pid, sig)
+        })
+    }
+}
+
+function detach() {
+    if (!attachment) return
+    const { binary, name } = attachment
+    attachment = null
+    spawnSync(binary, ["unuse", name, "--pid", String(process.pid)], { stdio: "ignore", env: process.env })
+}
+
+// ── the extension ──────────────────────────────────────────────────
+
+export default function cribsheet(pi: ExtensionAPI): void {
+    const notify = env("PI_CRIBSHEET_NOTIFY") !== "false"
+    const wantInstructions = env("PI_CRIBSHEET_INSTRUCTIONS") !== "false"
+    const wantCommand = env("PI_CRIBSHEET_COMMAND_ENABLE") !== "false"
+    const manage = env("PI_CRIBSHEET_MANAGE") !== "false"
+    const name = env("PI_CRIBSHEET_NAME") ?? DEFAULT_NAME
+    const served = combinerServes(name)
+
+    // ── directive: appended every turn (dup-guarded across turns) ──
+    pi.on("before_agent_start", (event) => {
+        if (!wantInstructions || !CRIB_DIRECTIVE) return
+        if (DIRECTIVE_MARKER && event.systemPrompt.includes(DIRECTIVE_MARKER)) return
+        return { systemPrompt: `${event.systemPrompt}\n\n${CRIB_DIRECTIVE}` }
+    })
+
+    // ── /crib command: recall memory + code index, then steer the model ──
+    if (wantCommand) {
+        pi.registerCommand("crib", {
+            description: "Consult crib (recall memory + code index); verb: system-prompt shows the directive",
+            getArgumentCompletions: (prefix) => completeVerbs(prefix),
+            handler: async (args, ctx) => {
+                const arg = args.trim()
+                if (arg === "system-prompt") {
+                    showDirective(ctx, "cribsheet", CRIB_DIRECTIVE, wantInstructions)
+                    return
+                }
+                const topic = arg
+                if (!topic) {
+                    ctx.ui?.notify?.("crib: give me a topic (e.g. /crib auth flow), or /crib system-prompt", "warn")
+                    return
+                }
+                const crib = resolveCrib()
+                if (!crib) {
+                    ctx.ui?.notify?.("crib: CLI not found; install cribsheet or set $PI_CRIBSHEET_COMMAND", "error")
+                    return
+                }
+                const run = async (sub: string[]) => {
+                    try {
+                        const r = await pi.exec(crib.cmd, [...crib.args, ...sub, topic], {
+                            signal: ctx.signal,
+                            timeout: 30_000,
+                        })
+                        return r.stdout.trim() || r.stderr.trim()
+                    } catch (e) {
+                        return `(crib ${sub.join(" ")} failed: ${e instanceof Error ? e.message : String(e)})`
+                    }
+                }
+                const [memory, code] = await Promise.all([run(["note", "apropos"]), run(["code", "lookup"])])
+                const content =
+                    `Consult crib first for "${topic}" — recalled below. Summarise what crib already knows: ` +
+                    "lead with the notes' answer, fold in any relevant code symbols, and cite note/symbol names " +
+                    "so the user can `crib note read` / `crib code dossier` to go deeper. If nothing relevant came " +
+                    "back, say so plainly rather than guessing.\n\n" +
+                    `Memory — semantic recall (crib note apropos):\n${memory}\n\n` +
+                    `Code index — symbols by concept or name (crib code lookup):\n${code}`
+                pi.sendMessage(
+                    { customType: "crib-recall", content, display: true, details: { topic } },
+                    { triggerTurn: true, deliverAs: "steer" },
+                )
+            },
+        })
+    }
+
+    // Combiner-served or manage=false: nothing to launch (crib runs elsewhere). The
+    // directive + command above still apply.
+    if (served || !manage) return
+
+    // ── process: launch on session_start, release on session_shutdown("quit") ──
+    pi.on("session_start", (_event, ctx) => {
+        if (attachment) return
+
+        const log = makeLog(ctx, notify)
+        const binary = resolveSharedserver(
+            {
+                label: "cribsheet",
+                minVersion: SHAREDSERVER_MIN_VERSION,
+                installerUrl:
+                    "https://github.com/georgeharker/sharedserver/releases/latest/download/sharedserver-installer.sh",
+            },
+            env("SHAREDSERVER_BIN"),
+            process.env,
+            log,
+        )
+        if (!binary) {
+            log("error", "sharedserver binary not found; set $SHAREDSERVER_BIN, or PI_CRIBSHEET_MANAGE=false")
+            return
+        }
+
+        const crib = resolveCrib()
+        if (!crib) {
+            log(
+                "error",
+                "crib command not found; install cribsheet (so `crib` is on PATH), or set " +
+                    "$PI_CRIBSHEET_COMMAND / $PI_CRIBSHEET_CHECKOUT",
+            )
+            return
+        }
+
+        const port = env("PI_CRIBSHEET_PORT") ?? String(DEFAULT_PORT)
+        const host = env("PI_CRIBSHEET_HOST") ?? DEFAULT_HOST
+        const grace = env("PI_CRIBSHEET_GRACE") ?? DEFAULT_GRACE
+
+        // Assemble: crib [extra] --mcp --http --host <host> --port <port>
+        const serve = ["--mcp", "--http", "--host", host, "--port", port]
+        const useArgs = [
+            "use",
+            name,
+            "--pid",
+            String(process.pid),
+            "--grace-period",
+            grace,
+            "--metadata",
+            `pi-${process.pid}`,
+        ]
+        const logFile = env("PI_CRIBSHEET_LOG")
+        if (logFile && logFile !== "none") useArgs.push("--log-file", logFile)
+        useArgs.push("--", crib.cmd, ...crib.args, ...serve)
+
+        installProcessCleanup()
+        const result = spawnSync(binary, useArgs, { stdio: "pipe", env: process.env })
+        if (result.error) {
+            log("error", `${name}: failed to spawn sharedserver (${result.error.message})`)
+            return
+        }
+        if (result.status !== 0) {
+            const stderr = result.stderr?.toString().trim()
+            log("error", `${name}: sharedserver use exited ${result.status}${stderr ? ` (${stderr})` : ""}`)
+            return
+        }
+
+        attachment = { binary, name }
+        log("info", `crib "${name}" attached on ${host}:${port} (${crib.cmd} ${crib.args.join(" ")})`)
+    })
+
+    pi.on("session_shutdown", (event: SessionShutdownEvent) => {
+        if (event.reason === "quit") detach()
+    })
+}
+
+// ── helpers ────────────────────────────────────────────────────────
+
+// Slash-command verbs. `system-prompt` shows the directive this extension injects — the
+// show-command pattern from pi-custom-system-prompt, since `before_agent_start`
+// injections are per-turn and never appear in Pi's own `/system-prompt` (base only).
+const COMMAND_VERBS = ["system-prompt"]
+function completeVerbs(prefix: string): AutocompleteItem[] | null {
+    const p = prefix.trim()
+    const matches = COMMAND_VERBS.filter((v) => v.startsWith(p))
+    return matches.length ? matches.map((v) => ({ value: v, label: v })) : null
+}
+
+const SHOW_LIMIT = 1600
+function showDirective(ctx: ExtensionCommandContext, label: string, directive: string, enabled: boolean): void {
+    if (!directive) {
+        ctx.ui?.notify?.(`${label}: no directive bundled (instructions.txt missing)`, "warn")
+        return
+    }
+    const head = enabled
+        ? `${label} directive — injected into the system prompt on every turn (before_agent_start):`
+        : `${label} directive — injection is DISABLED this session; it would be:`
+    const body =
+        directive.length > SHOW_LIMIT
+            ? `${directive.slice(0, SHOW_LIMIT)}\n\n… (${directive.length} chars total)`
+            : directive
+    ctx.ui?.notify?.(`${head}\n\n${body}`, "info")
+}
+
+function makeLog(ctx: ExtensionContext, notify: boolean): LogFn {
+    return (level, message) => {
+        const line = `cribsheet: ${message}`
+        if (notify && ctx.hasUI && ctx.ui?.notify) {
+            ctx.ui.notify(line, level === "error" ? "error" : level === "warn" ? "warn" : "info")
+        } else if (level === "error" || level === "warn") {
+            process.stderr.write(`${line}\n`)
+        }
+    }
+}

package/src/pi.ts

@@ -0,0 +1,70 @@
+// Narrow, local typing for the slice of Pi's extension API this plugin uses.
+//
+// Pi (badlogic/pi-mono, earendil-works/pi) ships its ExtensionAPI types with the
+// harness rather than as a standalone npm package we can depend on, so we declare
+// exactly the surface we touch — three lifecycle events, `registerCommand`, `exec`,
+// and `sendMessage`. Kept deliberately minimal: a wider mirror would rot against a
+// moving upstream. Signatures follow the published extension docs
+// (https://pi.dev/docs/latest/extensions).
+
+export type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork"
+export type SessionShutdownReason = "quit" | "reload" | "new" | "resume" | "fork"
+
+export type SessionStartEvent = { reason: SessionStartReason; previousSessionFile?: string }
+export type SessionShutdownEvent = { reason: SessionShutdownReason; targetSessionFile?: string }
+export type BeforeAgentStartEvent = { systemPrompt: string }
+export type BeforeAgentStartResult = { systemPrompt?: string } | void
+
+export type ExtensionContext = {
+    cwd: string
+    mode: "tui" | "rpc" | "json" | "print"
+    hasUI: boolean
+    signal?: AbortSignal
+    ui?: { notify?: (message: string, level?: "info" | "warn" | "error") => void }
+}
+
+/** Context handed to a command handler. Superset of ExtensionContext in practice; we
+ *  only read `signal`, `ui`, and `hasUI`. */
+export type ExtensionCommandContext = ExtensionContext
+
+export type AutocompleteItem = { value: string; label?: string }
+
+export type ExecResult = { stdout: string; stderr: string; code: number; killed: boolean }
+export type ExecOptions = { signal?: AbortSignal; timeout?: number; cwd?: string; env?: NodeJS.ProcessEnv }
+
+/** An LLM-visible message injected from a command. `display:true` shows it in the TUI;
+ *  `{triggerTurn:true, deliverAs:"steer"}` makes the model act on it this turn. */
+export type SendMessage = {
+    customType: string
+    content: string
+    display?: boolean
+    details?: Record<string, unknown>
+}
+export type SendMessageOptions = { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" }
+
+export type CommandSpec = {
+    description: string
+    handler: (args: string, ctx: ExtensionCommandContext) => void | Promise<void>
+    getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null
+}
+
+export interface ExtensionAPI {
+    on(
+        event: "session_start",
+        handler: (event: SessionStartEvent, ctx: ExtensionContext) => void | Promise<void>,
+    ): void
+    on(
+        event: "session_shutdown",
+        handler: (event: SessionShutdownEvent, ctx: ExtensionContext) => void | Promise<void>,
+    ): void
+    on(
+        event: "before_agent_start",
+        handler: (
+            event: BeforeAgentStartEvent,
+            ctx: ExtensionContext,
+        ) => BeforeAgentStartResult | Promise<BeforeAgentStartResult>,
+    ): void
+    registerCommand(name: string, spec: CommandSpec): void
+    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>
+    sendMessage(message: SendMessage, options?: SendMessageOptions): void
+}

package/src/sharedserver-resolve.ts

@@ -0,0 +1,221 @@
+// Resolve the `sharedserver` binary, fetching it when none is usable.
+//
+// VENDORED FILE. This is copied byte-identical into the consuming OpenCode plugins
+// (cribsheet, svg-mcp) by their scripts/sync-vendored.sh, so the drift check is a plain
+// diff. There is no way to share it as a dependency without coupling their versions to
+// sharedserver's — see plugins/claude/bin/sharedserver for the same reasoning on the
+// shell side. Edit it HERE; consumers re-sync.
+//
+// Everything repo-specific arrives through ResolveConfig rather than being hardcoded,
+// mirroring bin/sharedserver.conf.
+
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export type LogFn = (level: "info" | "warn" | "error", message: string) => void
+export type ToastFn = (variant: "success" | "warning" | "error", message: string) => void
+
+export type ResolveConfig = {
+    /** Prefix for user-facing messages. Default "sharedserver". */
+    label?: string
+    /** Minimum acceptable version. Defaults to pkgVersion (lockstep). */
+    minVersion?: string
+    /** Installer to fetch. Defaults to the release pinned to pkgVersion. */
+    installerUrl?: string
+    /** The host package's own version — only meaningful in lockstep mode. */
+    pkgVersion?: string
+}
+
+/** Oldest release these plugins are correct against: 0.5.0 added the PID-reuse guard,
+ *  without which a recycled client PID can hold a server open indefinitely. */
+const HARDCODED_FLOOR = "0.5.0"
+
+const CANDIDATE_BINARIES = [
+    "sharedserver",
+    join(homedir(), ".cargo", "bin", "sharedserver"),
+    join(homedir(), ".local", "bin", "sharedserver"),
+    "/usr/local/bin/sharedserver",
+    "/opt/homebrew/bin/sharedserver",
+]
+
+function parseVersion(text: string): [number, number, number] | undefined {
+    const m = text.match(/(\d+)\.(\d+)\.(\d+)/)
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined
+}
+
+function gte(a: [number, number, number], b: [number, number, number]): boolean {
+    for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i]
+    return true
+}
+
+function versionOf(candidate: string, env: NodeJS.ProcessEnv): [number, number, number] | undefined {
+    const r = spawnSync(candidate, ["--version"], { env })
+    if (r.error) return undefined
+    return parseVersion(`${r.stdout?.toString() ?? ""}${r.stderr?.toString() ?? ""}`)
+}
+
+/** Synchronous sleep — this path runs before anything can be awaited, so the lock wait
+ *  cannot use timers. Atomics.wait blocks without spinning. */
+function sleepSync(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/** First sharedserver found at ANY version, or undefined. */
+function probeAny(override: string | undefined, env: NodeJS.ProcessEnv): string | undefined {
+    const candidates = [override, env.SHAREDSERVER_BIN, ...CANDIDATE_BINARIES].filter(
+        (v): v is string => typeof v === "string" && v.length > 0,
+    )
+    for (const candidate of candidates) {
+        if (candidate.includes("/")) {
+            if (existsSync(candidate)) return candidate
+            continue
+        }
+        // Presence is "spawn did not fail", NOT "exited 0" — a build that rejects some
+        // flag is still present.
+        if (!spawnSync(candidate, ["--version"], { stdio: "ignore", env }).error) return candidate
+    }
+    return undefined
+}
+
+/** Download and run the cargo-dist installer, then re-probe. */
+function installPinned(
+    cfg: Required<Pick<ResolveConfig, "label">> & ResolveConfig,
+    url: string,
+    what: string,
+    env: NodeJS.ProcessEnv,
+    log?: LogFn,
+    toast?: ToastFn,
+): string | undefined {
+    // The SAME lock directory as the shell shim — cross-client coordination, so a
+    // Claude session and an OpenCode session starting together do not race.
+    const lockdir = join(env.TMPDIR || "/tmp", ".sharedserver-install.lock")
+    let haveLock = false
+    try {
+        mkdirSync(lockdir)
+        haveLock = true
+    } catch {
+        const deadline = Date.now() + 20_000
+        while (existsSync(lockdir) && Date.now() < deadline) sleepSync(250)
+        const after = probeAny(undefined, env)
+        if (after) return after
+        try {
+            mkdirSync(lockdir)
+            haveLock = true
+        } catch {
+            log?.("warn", `${cfg.label}: another process is installing sharedserver and did not finish; remove the stale lock if this persists: ${lockdir}`)
+            return undefined
+        }
+    }
+
+    try {
+        // Re-probe under the lock: the winner may have finished while we waited.
+        const already = probeAny(undefined, env)
+        const floor = parseVersion(cfg.minVersion ?? HARDCODED_FLOOR)
+        if (already) {
+            const v = versionOf(already, env)
+            if (v && floor && gte(v, floor)) return already
+        }
+
+        // Download to a file, then run it. `curl … | sh` would report success on a 404,
+        // since a pipeline's status is sh's; spawnSync uses no shell, so this is exact.
+        const script = join(lockdir, "installer.sh")
+        const dl = spawnSync("curl", ["--proto", "=https", "--tlsv1.2", "-LsSf", url, "-o", script], { env })
+        if (dl.error || dl.status !== 0) {
+            const msg = `${cfg.label}: could not download the sharedserver installer (${what})`
+            log?.("warn", msg)
+            toast?.("warning", msg)
+            return undefined
+        }
+        if (!existsSync(script) || statSync(script).size === 0) {
+            log?.("warn", `${cfg.label}: the downloaded sharedserver installer was empty`)
+            return undefined
+        }
+
+        // cargo-dist embeds the expected sha256 but looks up only `sha256sum` and SKIPS
+        // verification when missing — i.e. always, on macOS. Give it one (identical
+        // output) rather than execute an unverified binary.
+        let runEnv = env
+        if (spawnSync("sh", ["-c", "command -v sha256sum"], { stdio: "ignore" }).status !== 0) {
+            if (spawnSync("sh", ["-c", "command -v shasum"], { stdio: "ignore" }).status !== 0) {
+                log?.("warn", `${cfg.label}: refusing to install sharedserver — no sha256sum or shasum to verify the download`)
+                return undefined
+            }
+            writeFileSync(join(lockdir, "sha256sum"), '#!/bin/sh\nexec shasum -a 256 "$@"\n', { mode: 0o755 })
+            runEnv = { ...env, PATH: `${lockdir}:${env.PATH ?? ""}` }
+        }
+
+        const run = spawnSync("sh", [script], { env: runEnv, stdio: "ignore" })
+        if (run.error || run.status !== 0) {
+            log?.("warn", `${cfg.label}: the sharedserver installer ran but failed`)
+            return undefined
+        }
+        return probeAny(undefined, env)
+    } finally {
+        if (haveLock) {
+            try {
+                rmSync(lockdir, { recursive: true, force: true })
+            } catch {
+                /* best effort — a leaked lock costs the next run its bounded wait */
+            }
+        }
+    }
+}
+
+/** Resolve the sharedserver binary, fetching a release when nothing usable is present.
+ *
+ *  Behaviourally identical to plugins/claude/bin/sharedserver — same ladder, floor,
+ *  lock and degrade-rather-than-die fallback, so a user running both clients gets the
+ *  same answer to "which sharedserver am I on, and why". */
+export function resolveSharedserver(
+    cfg: ResolveConfig,
+    override: string | undefined,
+    env: NodeJS.ProcessEnv,
+    log?: LogFn,
+    toast?: ToastFn,
+): string | undefined {
+    const label = cfg.label ?? "sharedserver"
+    const minVersion = cfg.minVersion ?? cfg.pkgVersion ?? HARDCODED_FLOOR
+    const url =
+        cfg.installerUrl ??
+        (cfg.pkgVersion
+            ? `https://github.com/georgeharker/sharedserver/releases/download/v${cfg.pkgVersion}/sharedserver-installer.sh`
+            : "https://github.com/georgeharker/sharedserver/releases/latest/download/sharedserver-installer.sh")
+    const what = cfg.installerUrl || !cfg.pkgVersion ? "the latest release" : `v${cfg.pkgVersion}`
+    const resolved = { ...cfg, label, minVersion }
+    const floor = parseVersion(minVersion)
+
+    // An explicit binary / SHAREDSERVER_BIN is never second-guessed: the user named a
+    // specific one, so quietly downloading a different one is the wrong answer.
+    const explicit = override ?? env.SHAREDSERVER_BIN
+    if (explicit) {
+        const present = explicit.includes("/")
+            ? existsSync(explicit)
+            : !spawnSync(explicit, ["--version"], { stdio: "ignore", env }).error
+        if (present) {
+            const v = versionOf(explicit, env)
+            if (v && floor && !gte(v, floor)) {
+                const msg = `${label}: sharedserver at ${explicit} is ${v.join(".")}; this plugin expects >= ${minVersion}. Using it anyway because you set it explicitly.`
+                log?.("warn", msg)
+                toast?.("warning", msg)
+            }
+            return explicit
+        }
+    }
+
+    const found = probeAny(override, env)
+    if (found) {
+        const v = versionOf(found, env)
+        if (v && floor && gte(v, floor)) return found
+        // Too old: fetch, but remember this one — if the download fails we would rather
+        // run the old binary than nothing.
+        const msg = `${label}: sharedserver at ${found} is ${v?.join(".") ?? "an unknown version"}; this plugin expects >= ${minVersion}. Fetching ${what}. To keep your own build, set SHAREDSERVER_BIN=${found}`
+        log?.("warn", msg)
+        toast?.("warning", msg)
+        return installPinned(resolved, url, what, env, log, toast) ?? found
+    }
+
+    log?.("info", `${label}: no usable sharedserver found; fetching ${what} (one time). This needs no Rust toolchain.`)
+    return installPinned(resolved, url, what, env, log, toast)
+}