loopat 0.1.1 → 0.1.3

package/README.md

@@ -131,6 +131,14 @@ Loopat splits configuration along role lines — read whichever applies:
 
 ### Docker (recommended)
 
+Pull the prebuilt image from GHCR:
+
+```sh
+docker run -d --privileged -p 20001:10001 ghcr.io/simpx/loopat:latest
+```
+
+Or, to build from source and persist the workspace in a named volume:
+
 ```sh
 docker compose up -d
 ```

package/bin/loopat.mjs

@@ -19,6 +19,17 @@ const here = dirname(fileURLToPath(import.meta.url))
 const pkgRoot = join(here, "..")
 const serverEntry = join(pkgRoot, "server", "src", "index.ts")
 
+// Subcommand routing. `loopat uninstall` runs a standalone cleanup entry (never
+// boots the server); everything else starts the server. Kept here in the Node
+// shim so the uninstall path doesn't pull in any server-side init.
+const SUBCOMMANDS = {
+  uninstall: join(pkgRoot, "server", "src", "uninstall.ts"),
+}
+const sub = process.argv[2]
+const subEntry = Object.prototype.hasOwnProperty.call(SUBCOMMANDS, sub) ? SUBCOMMANDS[sub] : null
+const entry = subEntry ?? serverEntry
+const forwardArgs = subEntry ? process.argv.slice(3) : process.argv.slice(2)
+
 function resolveBun() {
   // 1. Explicit override.
   if (process.env.LOOPAT_BUN && existsSync(process.env.LOOPAT_BUN)) {
@@ -49,7 +60,7 @@ function resolveBun() {
 }
 
 const bun = resolveBun()
-const child = spawn(bun, [serverEntry, ...process.argv.slice(2)], {
+const child = spawn(bun, [entry, ...forwardArgs], {
   stdio: "inherit",
   env: process.env,
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopat",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Self-hosted AI workspace built around context management — works solo, scales to teams",
   "license": "Apache-2.0",
   "homepage": "https://github.com/simpx/loopat",

package/server/src/bootstrap.ts

@@ -22,16 +22,33 @@ import { listUsers } from "./auth"
 type Check = { ok: boolean; label: string; hint?: string }
 
 function checkPodman(): Check {
+  const isMac = process.platform === "darwin"
+  let version: string
   try {
-    const out = execFileSync("podman", ["--version"], { stdio: "pipe" }).toString().trim()
-    return { ok: true, label: `podman (sandbox): ${out}` }
+    version = execFileSync("podman", ["--version"], { stdio: "pipe" }).toString().trim()
   } catch {
     return {
       ok: false,
       label: "podman (sandbox)",
-      hint: "install with: sudo apt install podman uidmap fuse-overlayfs   (Linux only)",
+      hint: isMac
+        ? "brew install podman, then: podman machine init && podman machine start"
+        : "sudo apt install podman uidmap fuse-overlayfs   (Linux)",
     }
   }
+  // On macOS podman runs inside a Linux VM ("machine"). `--version` succeeds even
+  // when the machine is stopped — `podman info` is what actually needs the VM up.
+  if (isMac) {
+    try {
+      execFileSync("podman", ["info"], { stdio: "pipe", timeout: 8000 })
+    } catch {
+      return {
+        ok: false,
+        label: `podman (sandbox): ${version}`,
+        hint: "podman machine isn't running — start it: podman machine start   (run `podman machine init` first if you never have)",
+      }
+    }
+  }
+  return { ok: true, label: `podman (sandbox): ${version}` }
 }
 
 function checkClaudeBinary(): Check {
@@ -47,6 +64,21 @@ function checkClaudeBinary(): Check {
   }
 }
 
+function checkGitCrypt(): Check {
+  try {
+    const out = execFileSync("git-crypt", ["--version"], { stdio: "pipe" }).toString().trim()
+    return { ok: true, label: `git-crypt (personal vault): ${out}` }
+  } catch {
+    return {
+      ok: false,
+      label: "git-crypt (personal vault)",
+      hint: process.platform === "darwin"
+        ? "brew install git-crypt   (encrypts your personal vault)"
+        : "sudo apt install git-crypt   (encrypts your personal vault)",
+    }
+  }
+}
+
 
 function describeRemote(dir: string, url: string | undefined): string {
   if (!existsSync(dir)) return "missing"
@@ -92,6 +124,7 @@ export async function printBootstrapBanner(cfg: WorkspaceConfig) {
     { ok: existsSync(configPath()), label: `config: ${configPath()}` },
     checkPodman(),
     checkClaudeBinary(),
+    checkGitCrypt(),
   ]
 
   const bar = "─".repeat(60)

package/server/src/host-exec.ts

@@ -0,0 +1,129 @@
+/**
+ * host-cli proxy (POC). Some CLIs can only run on the host — macOS-only tools,
+ * or company tools bound to a specific machine. The sandbox can't run them, so
+ * we run them on the host *on behalf of* a loop:
+ *
+ *   sandbox:  `aone foo`  →  shim  →  loopat-host (forwarder)  →
+ *   server :  POST /api/host-exec  →  execFile("aone", ["foo"]) on the host
+ *
+ * Trust model (deliberately simple): mounting the socket into a sandbox IS the
+ * trust decision — a host that turns on host-cli for a loop already trusts that
+ * loop, so there is NO whitelist. The loop may run any host cli (it can call the
+ * forwarder directly with a hand-built command).
+ *
+ * The mise-generated shims aren't a whitelist either — they're the declarative
+ * ENTRY POINT. "Which clis did the loop declare in `[host].clis`" shows up as
+ * "which shim binaries exist on PATH"; that's a UX convention (what the AI can
+ * conveniently reach), not a security boundary. The only boundary is whether
+ * the socket is mounted at all.
+ *
+ *   - runs with HOST user permissions
+ *   - cwd is a per-loop host workdir (mirrors the loop's workdir); the cli
+ *     cannot see inside the sandbox
+ *   - execFile, never a shell — argv is an array
+ */
+import { execFile } from "node:child_process"
+import { mkdir, writeFile, chmod } from "node:fs/promises"
+import { existsSync, rmSync, mkdirSync } from "node:fs"
+import { join } from "node:path"
+import { loopDir, LOOPAT_HOME } from "./paths"
+
+/** A per-loop host workdir — the host-side mirror of the loop's own workdir. */
+export function hostWorkdir(loopId: string): string {
+  return join(loopDir(loopId), "host-workdir")
+}
+
+/** The dir that holds the host-exec unix socket. We mount the DIR (not the
+ *  socket file) into sandboxes so a server restart — which recreates the
+ *  socket inode — stays visible to already-running containers. */
+export function hostExecDir(): string {
+  return join(LOOPAT_HOME, "host-exec")
+}
+export function hostExecSocketPath(): string {
+  return join(hostExecDir(), "host-exec.sock")
+}
+
+export type HostExecResult =
+  | { ok: true; exitCode: number; stdout: string; stderr: string }
+  | { ok: false; error: string }
+
+/** Run a host-cli in the loop's host workdir, with host permissions. No
+ *  whitelist — mounting the socket into the sandbox is the trust decision. */
+export async function runHostCli(opts: {
+  cli: string
+  args: string[]
+  cwd: string
+  stdin?: string
+  timeoutMs?: number
+}): Promise<HostExecResult> {
+  await mkdir(opts.cwd, { recursive: true })
+  return new Promise((resolve) => {
+    const child = execFile(
+      opts.cli,
+      opts.args,
+      { cwd: opts.cwd, timeout: opts.timeoutMs ?? 120_000, maxBuffer: 16 * 1024 * 1024 },
+      (err: any, stdout, stderr) => {
+        if (err && err.code === "ENOENT") {
+          resolve({ ok: false, error: `host has no '${opts.cli}'` })
+          return
+        }
+        const exitCode = typeof err?.code === "number" ? err.code : err ? 1 : 0
+        resolve({ ok: true, exitCode, stdout: String(stdout), stderr: String(stderr) })
+      },
+    )
+    if (opts.stdin !== undefined && child.stdin) {
+      child.stdin.write(opts.stdin)
+      child.stdin.end()
+    }
+  })
+}
+
+/**
+ * Write a shim per declared host-cli into `binDir` (which the sandbox puts on
+ * PATH ahead of everything). Each shim just hands off to the forwarder.
+ */
+export async function writeHostShims(binDir: string, clis: string[]): Promise<void> {
+  await mkdir(binDir, { recursive: true })
+  // The `loopat-host` forwarder is baked into the sandbox image; here we only
+  // emit the per-cli shims — each just hands off to it.
+  for (const cli of clis) {
+    const p = join(binDir, cli)
+    await writeFile(p, `#!/bin/sh\n# loopat host-cli shim — forwards "${cli}" to the host\nexec loopat-host "${cli}" "$@"\n`)
+    await chmod(p, 0o755)
+  }
+}
+
+/**
+ * Unix-socket server that runs host-clis for loops. The sandbox's
+ * forwarder connects over the *mounted* socket — no TCP, no exposed port, and
+ * only a container that has the socket mounted can reach it (the mount itself
+ * is a layer of isolation). Reuses runHostCli. stdout/stderr come back base64
+ * so the sh forwarder can pull them out of the JSON without escaping pain.
+ */
+export function serveHostExec(socketPath: string, deps: { loopExists: (id: string) => Promise<boolean> }) {
+  try { mkdirSync(hostExecDir(), { recursive: true }) } catch {}
+  try { if (existsSync(socketPath)) rmSync(socketPath) } catch {}
+  return Bun.serve({
+    unix: socketPath,
+    async fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname !== "/host-exec" || req.method !== "POST") return new Response("not found", { status: 404 })
+      const b: any = await req.json().catch(() => ({}))
+      const loopId = typeof b.loopId === "string" ? b.loopId : ""
+      const cli = typeof b.cli === "string" ? b.cli : ""
+      const args = Array.isArray(b.args) ? b.args.map(String) : []
+      if (!loopId || !cli) return Response.json({ error: "loopId + cli required" })
+      if (!(await deps.loopExists(loopId))) return Response.json({ error: "unknown loop" })
+      const r = await runHostCli({
+        cli, args, cwd: hostWorkdir(loopId),
+        stdin: typeof b.stdin === "string" ? b.stdin : undefined,
+      })
+      if (!r.ok) return Response.json({ error: r.error })
+      return Response.json({
+        exitCode: r.exitCode,
+        stdout_b64: Buffer.from(r.stdout).toString("base64"),
+        stderr_b64: Buffer.from(r.stderr).toString("base64"),
+      })
+    },
+  })
+}

package/server/src/index.ts

@@ -55,6 +55,7 @@ import {
 import { loadConfig, loadPersonalConfig, savePersonalConfig, saveWorkspaceConfig, loadTokenUsage, getActiveProvider, readPersonalDiskRaw, savePersonalDisk, describeApiKeyRef, writeVaultEnv, deleteVaultEnv, type ProviderConfig, type ModelEntry } from "./config"
 import { listBoards, createBoard, renameBoard, listKanbanColumns, addCard, toggleCard, deleteCard, moveCard, updateCardMeta, updateCardBlock, reorderCards, createColumn, deleteColumn, readKanbanConfig, saveColumnOrder, setColumnColor, renameColumn, assignDriverForCard, createLoopFromCard, linkLoopToCard, kanbanUserCtx } from "./kanban"
 import { printBootstrapBanner } from "./bootstrap"
+import { serveHostExec, hostExecSocketPath } from "./host-exec"
 import {
   createUser,
   findUser,
@@ -3177,6 +3178,16 @@ await printBootstrapBanner(cfg)
 const backfilled = await backfillAllMounts()
 if (backfilled > 0) console.log(`[loopat] backfilled context mounts on ${backfilled} loop(s)`)
 
+// host-cli proxy: a unix socket the loop sandboxes mount + forward to, so
+// host-only clis (macOS / machine-bound) run on the host on behalf of a loop.
+try {
+  const sock = hostExecSocketPath()
+  serveHostExec(sock, { loopExists })
+  console.log(`[loopat] host-exec socket: ${sock}`)
+} catch (e: any) {
+  console.warn(`[loopat] host-exec socket failed: ${e?.message ?? e}`)
+}
+
 // Pull every imported personal repo from its remote on boot (best-effort).
 // personal is a per-user repo synced directly (not via loops), so a host that
 // was offline catches up here; settings edits then write-through on save.

package/server/src/loops.ts

@@ -1270,15 +1270,16 @@ export async function ensureUiNotesWorktree(user: string): Promise<void> {
 export async function syncUiNotes(user: string): Promise<PersonalPushResult> {
   const dir = uiNotesDir(user)
   await ensureUiNotesWorktree(user)
+  const branch = await remoteDefaultBranch(dir)
   const c = await commitLocalChanges(dir, "loopat: edit notes")
   if (!c.ok) return { ok: false, error: c.error }
-  const reb = await rebaseOntoOrigin(dir, "main")
+  const reb = await rebaseOntoOrigin(dir, branch)
   if (!reb.ok) {
     if ("conflict" in reb) return { ok: false, error: "conflict with remote", conflict: true, files: reb.files }
     return { ok: false, error: reb.error }
   }
   try {
-    await execFileP("git", ["-C", dir, "push", "origin", "HEAD:main"])
+    await execFileP("git", ["-C", dir, "push", "origin", `HEAD:${branch}`])
   } catch (e: any) {
     const stderr = (e?.stderr ?? "").toString().trim()
     return { ok: false, error: `push failed: ${stderr || e?.message || e}`, needsPull: true }
@@ -1296,6 +1297,7 @@ export async function ffUpdateUiNotes(
 ): Promise<{ ok: true } | { ok: false; diverged?: boolean; error: string }> {
   const dir = uiNotesDir(user)
   await ensureUiNotesWorktree(user)
+  const branch = await remoteDefaultBranch(dir)
   try {
     await execFileP("git", ["-C", dir, "fetch", "origin"], {
       env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, timeout: 30_000,
@@ -1305,12 +1307,12 @@ export async function ffUpdateUiNotes(
   }
   // No upstream yet → nothing to pull.
   try {
-    await execFileP("git", ["-C", dir, "rev-parse", "--verify", "--quiet", "origin/main"])
+    await execFileP("git", ["-C", dir, "rev-parse", "--verify", "--quiet", `origin/${branch}`])
   } catch {
     return { ok: true }
   }
   try {
-    await execFileP("git", ["-C", dir, "merge", "--ff-only", "origin/main"], {
+    await execFileP("git", ["-C", dir, "merge", "--ff-only", `origin/${branch}`], {
       env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
     })
     return { ok: true }
@@ -1327,6 +1329,7 @@ export async function ffUpdateUiNotes(
 export async function notesBehind(user: string): Promise<number> {
   const dir = uiNotesDir(user)
   await ensureUiNotesWorktree(user)
+  const branch = await remoteDefaultBranch(dir)
   try {
     await execFileP("git", ["-C", dir, "fetch", "origin"], {
       env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, timeout: 30_000,
@@ -1335,7 +1338,7 @@ export async function notesBehind(user: string): Promise<number> {
     return 0
   }
   try {
-    const { stdout } = await execFileP("git", ["-C", dir, "rev-list", "--count", "HEAD..origin/main"])
+    const { stdout } = await execFileP("git", ["-C", dir, "rev-list", "--count", `HEAD..origin/${branch}`])
     return parseInt(stdout.trim(), 10) || 0
   } catch {
     return 0
@@ -1655,10 +1658,13 @@ async function ensureContextWorktree(repo: string, path: string, branchName: str
 
   // Stale state (old symlink, empty dir, leftover from manual cleanup) → wipe + create.
   try { await rm(path, { recursive: true, force: true }) } catch {}
-  // ① pull (docs/context-flow.md): open the worktree from origin/main so the
-  // loop starts from latest consensus, not a possibly-stale local HEAD.
+  try { await execFileP("git", ["-C", repo, "worktree", "prune"]) } catch {}
+  // ① pull (docs/context-flow.md): open the worktree from origin's default
+  // branch so the loop starts from latest consensus, not a stale local HEAD.
   const start = await remoteStartPoint(repo)
-  const args = ["-C", repo, "worktree", "add", "-b", branchName, path]
+  // -B (not -b): reset the branch if it lingers from a removed worktree, so a
+  // rebuild always re-opens cleanly from the start point.
+  const args = ["-C", repo, "worktree", "add", "-B", branchName, path]
   if (start) args.push(start)
   await execFileP("git", args)
 }
@@ -1669,6 +1675,22 @@ async function ensureContextWorktree(repo: string, path: string, branchName: str
  * loop opens from the latest shared state. Returns null to fall back to local
  * HEAD (solo / offline / no remote / no origin/main yet).
  */
+/** The remote's default branch (origin/HEAD) — e.g. main or master. Falls back
+ *  to "main". loopat must NOT assume "main": team repos are often on "master". */
+async function remoteDefaultBranch(dir: string): Promise<string> {
+  try {
+    const { stdout } = await execFileP("git", ["-C", dir, "symbolic-ref", "--short", "refs/remotes/origin/HEAD"])
+    const b = stdout.trim().replace(/^origin\//, "")
+    if (b) return b
+  } catch {}
+  try {
+    const { stdout } = await execFileP("git", ["-C", dir, "ls-remote", "--symref", "origin", "HEAD"])
+    const m = stdout.match(/ref:\s+refs\/heads\/(\S+)\s+HEAD/)
+    if (m?.[1]) return m[1]
+  } catch {}
+  return "main"
+}
+
 async function remoteStartPoint(repo: string): Promise<string | null> {
   try {
     await execFileP("git", ["-C", repo, "remote", "get-url", "origin"])
@@ -1678,9 +1700,10 @@ async function remoteStartPoint(repo: string): Promise<string | null> {
   try {
     await execFileP("git", ["-C", repo, "fetch", "--quiet", "origin"], { timeout: 15_000 })
   } catch {}
+  const branch = await remoteDefaultBranch(repo)
   try {
-    await execFileP("git", ["-C", repo, "rev-parse", "--verify", "--quiet", "origin/main^{commit}"])
-    return "origin/main"
+    await execFileP("git", ["-C", repo, "rev-parse", "--verify", "--quiet", `origin/${branch}^{commit}`])
+    return `origin/${branch}`
   } catch {
     return null
   }

package/server/src/podman.ts

@@ -36,7 +36,7 @@
 import { execFile, spawn } from "node:child_process"
 import { createHash } from "node:crypto"
 import { existsSync } from "node:fs"
-import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
 import { homedir, tmpdir } from "node:os"
 import { join } from "node:path"
 import { promisify } from "node:util"
@@ -59,6 +59,8 @@ import {
 } from "./paths"
 import { loadConfig } from "./config"
 import { DEFAULT_VAULT, listVaultHomeMounts } from "./vaults"
+import { hostExecDir, writeHostShims } from "./host-exec"
+import { parse as tomlParse, stringify as tomlStringify } from "smol-toml"
 
 const execFileP = promisify(execFile)
 
@@ -75,6 +77,13 @@ export const V_CONTEXT_PERSONAL_MEMORY = "/loopat/context/personal/memory"
 export const V_CONTEXT_REPOS = "/loopat/context/repos"
 export const V_CONTEXT_CHAT = "/loopat/context/chat"
 
+// host-cli proxy: the dir holding the host-exec unix socket, mounted in so the
+// loop's `loopat-host` forwarder can reach the host. Mount the DIR (not the
+// socket file) so a server restart that recreates the socket inode stays
+// visible inside running containers.
+export const V_HOST_EXEC_DIR = "/loopat/host-exec"
+export const V_HOST_EXEC_SOCK = "/loopat/host-exec/host-exec.sock"
+
 // $HOME inside the container. Deliberately NOT host's homedir — if we bound
 // host's $HOME at its real path, podman would auto-create parent dirs for
 // every nested bind (LOOPAT_HOME, LOOPAT_INSTALL_DIR, etc. all live under
@@ -247,6 +256,15 @@ export async function buildVolumeMounts(opts: ContainerOptions): Promise<VolumeM
     mounts.push({ src: chatDir, dst: V_CONTEXT_CHAT, ro: true })
   }
 
+  // host-cli proxy: mount the host-exec socket dir so the loop's `loopat-host`
+  // forwarder can reach the host. Mounting the socket IS the trust decision —
+  // a loop with this mount may run any host cli (see host-exec.ts). The dir is
+  // created by serveHostExec at boot; mount if present (bind-try semantics).
+  const hostExec = hostExecDir()
+  if (existsSync(hostExec)) {
+    mounts.push({ src: hostExec, dst: V_HOST_EXEC_DIR })
+  }
+
   // All-loops ro view (admin-gated): expose LOOPAT_HOME/loops/ at /loopat/loops.
   if (mountAllLoops) {
     mounts.push({ src: loopsDir(), dst: V_ALL_LOOPS, ro: true })
@@ -292,6 +310,10 @@ export async function buildContainerEnv(opts: ContainerOptions): Promise<Record<
   const out: Record<string, string> = {}
   // Sandbox $HOME is /loopat/home/<user> (see V_HOME comment).
   out.HOME = V_HOME(opts.createdBy)
+  // host-cli proxy: tell the loop's `loopat-host` forwarder where the mounted
+  // socket is and which loop it speaks for (server uses it for the workdir).
+  out.LOOPAT_HOST_SOCK = V_HOST_EXEC_SOCK
+  out.LOOPAT_LOOP_ID = opts.loopId
   for (const [k, v] of Object.entries(opts.extraEnv ?? {})) {
     out[k] = v
   }
@@ -508,12 +530,17 @@ export async function probePodman(): Promise<PodmanProbeResult> {
  *  through and invalidate stale child images.
  */
 export async function baseContainerfileHash(): Promise<string> {
-  const containerfile = join(LOOPAT_INSTALL_DIR, "server", "templates", "sandbox", "Containerfile")
+  const dir = join(LOOPAT_INSTALL_DIR, "server", "templates", "sandbox")
+  const containerfile = join(dir, "Containerfile")
   if (!existsSync(containerfile)) {
     throw new Error(`Containerfile not found at ${containerfile}`)
   }
-  const content = await readFile(containerfile, "utf8")
-  return createHash("sha256").update(content).digest("hex").slice(0, 16)
+  const h = createHash("sha256").update(await readFile(containerfile, "utf8"))
+  // Files COPY'd by the Containerfile also affect the image — hash them too so
+  // editing the forwarder rebuilds the base image.
+  const forwarder = join(dir, "loopat-host")
+  if (existsSync(forwarder)) h.update(await readFile(forwarder, "utf8"))
+  return h.digest("hex").slice(0, 16)
 }
 
 let _imageBuildInFlight: Promise<void> | null = null
@@ -649,19 +676,44 @@ export async function ensureLoopImage(loopId: string, opts?: { onProgress?: (msg
     opts?.onProgress?.("Installing tools from mise.toml…")
     const buildDir = await mkdtemp(join(tmpdir(), "loopat-img-"))
     try {
-      await copyFile(miseTomlPath, join(buildDir, "mise.toml"))
+      // A loopat-native `[host]` table declares host-only clis (macOS /
+      // machine-bound) the sandbox can't run natively. We bake a forwarding
+      // shim per cli into the image's mise shims dir (already first on PATH),
+      // and strip the table before mise sees it — mise would reject the
+      // unknown table. The shim just hands off to `loopat-host` (in the base
+      // image) → mounted socket → host execFile. See host-exec.ts.
+      let hostClis: string[] = []
+      let miseConfig = content
+      try {
+        const parsed: any = tomlParse(content)
+        if (parsed && Array.isArray(parsed.host?.clis)) {
+          hostClis = parsed.host.clis.filter((x: unknown): x is string => typeof x === "string" && !!x)
+        }
+        if (parsed && "host" in parsed) {
+          const { host: _host, ...rest } = parsed
+          miseConfig = tomlStringify(rest)
+        }
+      } catch {}
+      await writeFile(join(buildDir, "mise.toml"), miseConfig)
       // Override `mise trust` interactively by marking the config path
       // trusted via env. `mise install -y` installs everything in
       // mise.toml; `mise reshim` ensures /opt/loopat-mise/shims/ has a
       // shim for every tool.
-      const childContainerfile = [
+      const lines = [
         `FROM ${SANDBOX_IMAGE}`,
         `COPY mise.toml /opt/loopat-mise/config/config.toml`,
         `RUN MISE_TRUSTED_CONFIG_PATHS=/opt/loopat-mise/config/config.toml \\`,
         `    mise install -y \\`,
         ` && MISE_TRUSTED_CONFIG_PATHS=/opt/loopat-mise/config/config.toml \\`,
         `    mise reshim`,
-      ].join("\n") + "\n"
+      ]
+      if (hostClis.length) {
+        // Generate the shims into the build context, then COPY them in AFTER
+        // reshim so mise's own reshim can't clobber them.
+        await writeHostShims(join(buildDir, "host-bin"), hostClis)
+        lines.push(`COPY host-bin/ /opt/loopat-mise/shims/`)
+      }
+      const childContainerfile = lines.join("\n") + "\n"
       await writeFile(join(buildDir, "Containerfile"), childContainerfile)
 
       const r = await runPodman(
@@ -883,17 +935,26 @@ let _portProxyReady: Promise<void> | null = null
  */
 function findOccupiedPorts(lo: number, hi: number): Set<number> {
   const ports = new Set<number>()
+  const { execFileSync } = require("node:child_process")
+  const add = (port: number) => { if (port >= lo && port <= hi) ports.add(port) }
+  // Linux: ss reads /proc/net/tcp (every listening socket).
   try {
-    const { execFileSync } = require("node:child_process")
     const out = execFileSync("ss", ["-tlnH"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }) as string
     for (const line of out.split("\n")) {
       const parts = line.trim().split(/\s+/)
       if (parts.length < 4) continue
-      const addr = parts[3] // e.g. "0.0.0.0:8080" or "[::]:8080" or "127.0.0.1:8080"
+      const addr = parts[3] // "0.0.0.0:8080" | "[::]:8080" | "127.0.0.1:8080"
       const colonIdx = addr.lastIndexOf(":")
-      if (colonIdx === -1) continue
-      const port = Number(addr.slice(colonIdx + 1))
-      if (port >= lo && port <= hi) ports.add(port)
+      if (colonIdx !== -1) add(Number(addr.slice(colonIdx + 1)))
+    }
+    return ports
+  } catch {}
+  // macOS (no ss): lsof. NAME column looks like "*:8080" or "127.0.0.1:8080 (LISTEN)".
+  try {
+    const out = execFileSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }) as string
+    for (const line of out.split("\n")) {
+      const m = line.match(/:(\d+)\s*\(LISTEN\)/)
+      if (m) add(Number(m[1]))
     }
   } catch {}
   return ports