loopat 0.1.0

package/server/src/paths.ts

@@ -0,0 +1,190 @@
+import { homedir } from "node:os"
+import { basename, dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/**
+ * LOOPAT_HOME *is* the workspace directory. Single-workspace by design — to
+ * run a second workspace, start a second loopat instance with a different
+ * LOOPAT_HOME. Default `~/.loopat`. The display/URL name is the basename
+ * with leading dots stripped (so `~/.loopat` → "loopat").
+ */
+export const LOOPAT_HOME = process.env.LOOPAT_HOME ?? join(homedir(), ".loopat")
+
+// loopat code install dir (contains node_modules/, helper binaries the sandbox needs)
+// Computed from this file's path: server/src/paths.ts → loop/
+const __DIRNAME = dirname(fileURLToPath(import.meta.url))
+export const LOOPAT_INSTALL_DIR = resolve(__DIRNAME, "../..")
+export const TEMPLATES_DIR = join(LOOPAT_INSTALL_DIR, "server", "templates")
+
+export const WORKSPACE = basename(LOOPAT_HOME).replace(/^\.+/, "") || "loopat"
+
+export const workspaceDir = () => LOOPAT_HOME
+export const usersPath = () => join(LOOPAT_HOME, "users.json")
+export const loopsDir = () => join(LOOPAT_HOME, "loops")
+export const workspaceContextDir = () => join(LOOPAT_HOME, "context")
+export const workspaceKnowledgeDir = () => join(workspaceContextDir(), "knowledge")
+export const workspaceNotesDir = () => join(workspaceContextDir(), "notes")
+export const workspaceReposDir = () => join(workspaceContextDir(), "repos")
+export const workspaceRepoDir = (name: string) => join(workspaceReposDir(), name)
+// Local git hosting: when a context repo has no remote, loopat hosts the
+// `origin` itself as a bare repo here (docs/context-flow.md "solo").
+export const workspaceOriginsDir = () => join(LOOPAT_HOME, "origins")
+export const workspaceOriginPath = (name: string) => join(workspaceOriginsDir(), `${name}.git`)
+// External git-host provider extensions (e.g. internal "Code" platform). Drop a
+// duck-typed provider file here; loopat loads it without any core change.
+export const extensionsProvidersDir = () => join(LOOPAT_HOME, "extensions", "providers")
+export const personalDir = (user: string) => join(LOOPAT_HOME, "personal", user)
+
+export const loopDir = (id: string) => join(loopsDir(), id)
+export const loopWorkdir = (id: string) => join(loopDir(id), "workdir")
+export const loopClaudeDir = (id: string) => join(loopDir(id), ".claude")
+export const loopContextDir = (id: string) => join(loopDir(id), "context")
+export const loopContextKnowledge = (id: string) => join(loopContextDir(id), "knowledge")
+export const loopContextNotes = (id: string) => join(loopContextDir(id), "notes")
+export const loopContextPersonal = (id: string) => join(loopContextDir(id), "personal")
+export const loopContextRepos = (id: string) => join(loopContextDir(id), "repos")
+export const loopContextChatDir = (id: string) => join(loopContextDir(id), "chat")
+export const loopMetaPath = (id: string) => join(loopDir(id), "meta.json")
+
+// UI loop checkouts — a per-user worktree for editing team context (notes) from
+// outside any AI loop (a "no-AI UI loop", see docs/context-flow.md). Disposable:
+// opened from origin/main, synced back ff-only.
+export const uiDir = (user: string) => join(LOOPAT_HOME, "ui", user)
+export const uiNotesDir = (user: string) => join(uiDir(user), "notes")
+export const loopHistoryPath = (id: string) => join(loopDir(id), "messages.jsonl")
+export const loopChatHistoryPath = (id: string) => join(loopDir(id), "chat_history.jsonl")
+
+export const chatDbPath = () => join(LOOPAT_HOME, "chat.db")
+
+export const personalMemoryDir = (user: string) => join(personalDir(user), "memory")
+export const workspaceMemoryDir = () => join(workspaceNotesDir(), "memory")
+// (Old `workspaceLoopat{Reserved,Claude,Skills,Agents,Sandbox*}` helpers
+// deleted — superseded by the tiered .claude/ model. Workspace CC config now
+// lives at `<knowledge>/.loopat/.claude/` and is accessed via
+// `workspaceTeamClaudeDir/SettingsPath/ClaudeMdPath/SkillsDir/AgentsDir` below.)
+
+// Per-loop $HOME overlay (docker container layer for home). The sandbox's
+// $HOME is an overlayfs mount: lower = workspaceHomeSkelDir (shared skeleton,
+// typically empty), upper = home-upper (per-loop persistent diff), work =
+// home-work (overlayfs internal scratch). merged is the mount point that
+// bwrap binds into the sandbox at $HOME. Persists across loop restarts; AI's
+// pip/npm installs and shell history survive.
+export const loopHomeUpper = (id: string) => join(loopDir(id), "home-upper")
+export const loopHomeWork = (id: string) => join(loopDir(id), "home-work")
+export const loopHomeMerged = (id: string) => join(loopDir(id), "home-merged")
+// Workspace-shared base layer for the home overlay. User can drop default
+// dotfiles in here; left empty by default.
+export const workspaceHomeSkelDir = () => join(LOOPAT_HOME, "sandbox-home-skel")
+// Bundled platform doctrine — ships with loopat code, always present.
+export const bundledDoctrinePath = () => join(TEMPLATES_DIR, "CLAUDE.md")
+
+// Per-loop-kind templates (distill, future: review, plan, etc.). Each kind
+// has its own dir; createLoop / distillLoop copies the kind's CLAUDE.md into
+// the new loop's workdir as the L2++ project-tier doctrine.
+export const loopKindTemplateDir = (kind: string) => join(TEMPLATES_DIR, "loop-kinds", kind)
+export const loopKindClaudePath = (kind: string) => join(loopKindTemplateDir(kind), "CLAUDE.md")
+
+// Personal `.loopat/` reserved namespace: per-user loopat config + vaults.
+// Mirrors `knowledge/.loopat/` as the personal counterpart.
+//
+// Vault model: each loop selects one vault (default = "default"). The vault is
+// NOT exposed to the sandbox as a directory. Instead two filesystem conventions
+// inside the vault drive automatic delivery at spawn time:
+//   - `vaults/<v>/envs/<NAME>`            → injected as env var $NAME
+//   - `vaults/<v>/mounts/home/<rel>/...`  → bound at $HOME/<rel>/...
+// AI never sees "vault" as a concept — it just sees a configured machine.
+export const personalLoopatDir = (user: string) => join(personalDir(user), ".loopat")
+export const personalLoopatConfigPath = (user: string) => join(personalLoopatDir(user), "config.json")
+export const personalVaultsDir = (user: string) => join(personalLoopatDir(user), "vaults")
+// Personal `.claude/` — CC-native shape. The 4th layer in loopat's tiered
+// .claude merge (workspace + profiles + personal + repo). Lives under
+// `.loopat/` to mirror the team convention (`knowledge/.loopat/.claude/`):
+// loopat-controlled config goes under `.loopat/` so the personal repo's
+// other content (memory, scratch files) stays cleanly separate.
+// Contains: settings.json, CLAUDE.md, skills/, agents/.
+export const personalClaudeDir = (user: string) => join(personalLoopatDir(user), ".claude")
+export const personalClaudeMdPath = (user: string) => join(personalClaudeDir(user), "CLAUDE.md")
+export const personalSettingsPath = (user: string) => join(personalClaudeDir(user), "settings.json")
+export const personalSkillsDir = (user: string) => join(personalClaudeDir(user), "skills")
+export const personalAgentsDir = (user: string) => join(personalClaudeDir(user), "agents")
+// Composed output inside each loop's .claude/. Regenerated every spawn.
+// Plugin loading does NOT touch the loop's .claude/ — SDK loads plugins via
+// its `plugins` option (resolved from server cache; see plugin-installer.ts).
+export const loopComposedSkillsDir = (id: string) => join(loopDir(id), ".claude", "skills")
+export const loopComposedAgentsDir = (id: string) => join(loopDir(id), ".claude", "agents")
+
+// Platform-shipped builtin plugins live under server/templates/plugins/<name>/.
+// They're always loaded into every loop (plugin-installer.ts:resolveBuiltinPlugins).
+// No marketplace wrapper — direct path injection via SDK plugins option.
+export const personalVaultDir = (user: string, vault: string) => join(personalVaultsDir(user), vault)
+/** Convention dir: every file under this dir is auto-injected as an env var
+ *  at spawn time. Filename = env var name. content = value (trailing newline
+ *  stripped). Subdirs not recursed. */
+export const personalVaultEnvsDir = (user: string, vault: string) =>
+  join(personalVaultDir(user, vault), "envs")
+/** Path to a specific env-var file inside the vault. */
+export const personalVaultEnvPath = (user: string, vault: string, name: string) =>
+  join(personalVaultEnvsDir(user, vault), name)
+/** Convention dir: every top-level entry under this is auto-bound at the
+ *  corresponding $HOME-relative path. e.g. `mounts/home/.ssh/` → `$HOME/.ssh/`. */
+export const personalVaultMountsHomeDir = (user: string, vault: string) =>
+  join(personalVaultDir(user, vault), "mounts", "home")
+
+// Host-only per-user state: deploy key (loopat → personal repo) and git-crypt
+// key (decrypts secrets/ inside the cloned personal repo). Kept OUTSIDE
+// personal/<user>/ so it never appears in the sandbox bind view. The user
+// can't see these from inside their loop's terminal / file browser.
+export const hostSecretsDir = (user: string) => join(LOOPAT_HOME, "host-secrets", user)
+export const hostDeployKeyPath = (user: string) => join(hostSecretsDir(user), "deploy-key")
+export const hostDeployKeyPubPath = (user: string) => join(hostSecretsDir(user), "deploy-key.pub")
+export const personalGitCryptKeyPath = (user: string) => join(hostSecretsDir(user), "git-crypt.key")
+export const personalTokenUsagePath = (user: string) => join(personalLoopatDir(user), "token-usage.json")
+export const workspaceSecretsDir = () => join(workspaceDir(), "secrets")
+
+// ─── Profile composition model (post-2026-05 design, CC-native refactor) ─
+//
+// See docs/composition.md. The team workspace lives inside the
+// knowledge git repo at `.loopat/`, structured as a stack of CC-native
+// `.claude/` directories — one per tier (team / profile). loopat materializes
+// a merge of selected tiers into each loop's `.claude/`.
+//
+//   knowledge/.loopat/
+//     .claude/                                ← team-tier CC config
+//       settings.json (enabledPlugins, extraKnownMarketplaces)
+//       CLAUDE.md, skills/, agents/
+//     profiles/<name>/.claude/                ← profile-tier CC config
+//       settings.json, CLAUDE.md, skills/, agents/
+//     marketplace/                            ← team's local CC marketplace
+//       .claude-plugin/marketplace.json
+//       <plugin>/...
+//
+// No loopat-invented schema (profile.json gone). Admins use CC's own
+// commands (`claude plugin install --scope=project` etc.) inside these
+// dirs to edit team / profile configuration.
+export const workspaceLoopatRoot = () => join(workspaceKnowledgeDir(), ".loopat")
+
+// Team-tier .claude/ — analogous to ~/.claude/ but shared across team via git.
+export const workspaceTeamClaudeDir = () => join(workspaceLoopatRoot(), ".claude")
+export const workspaceTeamSettingsPath = () => join(workspaceTeamClaudeDir(), "settings.json")
+export const workspaceTeamClaudeMdPath = () => join(workspaceTeamClaudeDir(), "CLAUDE.md")
+export const workspaceTeamSkillsDir = () => join(workspaceTeamClaudeDir(), "skills")
+export const workspaceTeamAgentsDir = () => join(workspaceTeamClaudeDir(), "agents")
+
+// Profiles — each is a dir with a `.claude/` subdir (CC project-tier shape).
+export const workspaceProfilesDir = () => join(workspaceLoopatRoot(), "profiles")
+export const workspaceProfileDir = (name: string) => join(workspaceProfilesDir(), name)
+export const workspaceProfileClaudeDir = (name: string) =>
+  join(workspaceProfileDir(name), ".claude")
+export const workspaceProfileSettingsPath = (name: string) =>
+  join(workspaceProfileClaudeDir(name), "settings.json")
+export const workspaceProfileClaudeMdPath = (name: string) =>
+  join(workspaceProfileClaudeDir(name), "CLAUDE.md")
+export const workspaceProfileSkillsDir = (name: string) =>
+  join(workspaceProfileClaudeDir(name), "skills")
+export const workspaceProfileAgentsDir = (name: string) =>
+  join(workspaceProfileClaudeDir(name), "agents")
+
+// (Marketplace location is NOT a loopat convention. Teams choose where to
+// host private plugins — typically `<knowledge>/marketplace/` — and declare
+// it via `extraKnownMarketplaces` in their team `.claude/settings.json`.
+// loopat just registers whatever's declared; it doesn't probe fixed paths.)

package/server/src/personal-keys.ts

@@ -0,0 +1,60 @@
+/**
+ * Loopat-managed SSH keypair for the user's personal git repo (deploy key).
+ *
+ * Lives under `host-secrets/<user>/deploy-key` — OUTSIDE personal/<user>/ so
+ * it never enters the sandbox bind view. The user can't see this key from
+ * inside their loop. It's loopat-the-platform's clone credential, not a
+ * user-owned tool.
+ *
+ * Public key is rendered to the UI once at register time so the user can
+ * register it as a deploy key on their personal git repo (aone / github).
+ *
+ * Idempotent: if the keypair already exists, returns the existing public key.
+ */
+import { existsSync } from "node:fs"
+import { mkdir, readFile, chmod } from "node:fs/promises"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import {
+  hostSecretsDir,
+  hostDeployKeyPath,
+  hostDeployKeyPubPath,
+} from "./paths"
+
+const execFileP = promisify(execFile)
+
+/**
+ * Generate ed25519 keypair if missing. Tolerant: if `ssh-keygen` is not on
+ * PATH (host missing openssh-client) returns `{ publicKey: null }` so the
+ * rest of register/provision proceeds — user can install ssh-keygen later
+ * and retrigger key gen via /api/personal/import (which calls this again).
+ */
+export async function ensurePersonalKeypair(userId: string): Promise<{ publicKey: string | null }> {
+  const dir = hostSecretsDir(userId)
+  const priv = hostDeployKeyPath(userId)
+  const pub = hostDeployKeyPubPath(userId)
+
+  await mkdir(dir, { recursive: true })
+  await chmod(dir, 0o700).catch(() => {})
+
+  if (!existsSync(priv) || !existsSync(pub)) {
+    const comment = `loopat:${userId}`
+    try {
+      await execFileP("ssh-keygen", ["-t", "ed25519", "-N", "", "-C", comment, "-f", priv, "-q"])
+    } catch (e: any) {
+      console.warn(`[loopat] ssh-keygen failed for user=${userId}: ${e?.message ?? e}. Install openssh-client to enable deploy-key flow.`)
+      return { publicKey: null }
+    }
+    await chmod(priv, 0o600).catch(() => {})
+    await chmod(pub, 0o644).catch(() => {})
+  }
+
+  const publicKey = (await readFile(pub, "utf8")).trim()
+  return { publicKey }
+}
+
+export async function getPublicKey(userId: string): Promise<string | null> {
+  const pub = hostDeployKeyPubPath(userId)
+  if (!existsSync(pub)) return null
+  return (await readFile(pub, "utf8")).trim()
+}

package/server/src/plugin-installer.ts

@@ -0,0 +1,287 @@
+/**
+ * Plugin orchestration on the host. Post-wholesale-bind (2026-05): the inner
+ * SDK now resolves enabledPlugins natively because bwrap.ts ro-binds
+ * ~/.claude/plugins/ wholesale into the sandbox. So loopat's job here is
+ * purely host-side preparation:
+ *
+ *   1. Make sure every marketplace declared in the loop's merged
+ *      `extraKnownMarketplaces` is registered with the host CC.
+ *   2. Make sure every spec in `enabledPlugins` is installed in the host CC
+ *      cache (otherwise SDK would find an enabled-but-uninstalled spec and
+ *      fail to load it).
+ *
+ * That's it — no path resolution, no return value beyond success/failure. The
+ * `plugins:` SDK option is reserved for the loopat-shipped builtin (which
+ * lives under LOOPAT_INSTALL_DIR, not in CC's plugin cache).
+ *
+ * `lookupPluginInstallPath` remains a host-side utility for the slash-command
+ * pre-seed (session.ts) and the loop-stats preview (loop-stats.ts).
+ */
+import { existsSync, statSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { execFile } from "node:child_process"
+import { homedir } from "node:os"
+import { join, resolve as resolvePath } from "node:path"
+import { promisify } from "node:util"
+import { TEMPLATES_DIR, loopClaudeDir } from "./paths"
+
+const execFileP = promisify(execFile)
+
+/** loopat-shipped builtin plugin (not in CC's plugin cache; passed via SDK option). */
+export const BUILTIN_LOOPAT_PLUGIN_PATH = join(TEMPLATES_DIR, "plugins", "loopat")
+
+const USER_CLAUDE_DIR = join(homedir(), ".claude")
+const USER_INSTALLED_PLUGINS = join(USER_CLAUDE_DIR, "plugins", "installed_plugins.json")
+const USER_KNOWN_MARKETPLACES = join(USER_CLAUDE_DIR, "plugins", "known_marketplaces.json")
+
+type InstalledPluginsFile = {
+  version: number
+  plugins: Record<string, Array<{ installPath: string; version: string; scope?: string }>>
+}
+type KnownMarketplacesFile = Record<string, { installLocation?: string; source?: any }>
+type MarketplaceCatalog = {
+  plugins?: Array<{ name: string; source: string | { source: string; [k: string]: any } }>
+}
+
+async function readJsonOpt<T>(path: string): Promise<T | null> {
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as T
+  } catch {
+    return null
+  }
+}
+
+async function runClaude(args: string[]): Promise<{ ok: boolean; out: string; err: string }> {
+  try {
+    const { stdout, stderr } = await execFileP("claude", args)
+    return { ok: true, out: stdout, err: stderr }
+  } catch (e: any) {
+    return {
+      ok: false,
+      out: e?.stdout?.toString?.() ?? "",
+      err: e?.stderr?.toString?.() ?? e?.message ?? String(e),
+    }
+  }
+}
+
+/**
+ * Compare two marketplace sources (from settings.json and from CC's
+ * known_marketplaces.json). Used to detect URL/path drift — if a team admin
+ * changes the marketplace URL, members' host CC needs to re-register.
+ */
+export function sourcesMatch(declared: any, existing: any): boolean {
+  if (declared === existing) return true
+  if (!declared || !existing) return false
+  if (typeof declared !== "object" || typeof existing !== "object") return false
+  if (declared.source !== existing.source) return false
+  switch (declared.source) {
+    case "git":
+    case "url":
+      return declared.url === existing.url
+    case "github":
+      return (declared.repo ?? declared.repository) === (existing.repo ?? existing.repository)
+    case "directory":
+      return declared.path === existing.path
+    default:
+      return JSON.stringify(declared) === JSON.stringify(existing)
+  }
+}
+
+async function ensureMarketplace(
+  name: string,
+  addPath: string,
+  declaredSource: any,
+  km: KnownMarketplacesFile | null,
+): Promise<void> {
+  const existing = (km?.[name] as any)?.source
+  if (existing) {
+    if (sourcesMatch(declaredSource, existing)) return
+    console.warn(
+      `[plugins] marketplace "${name}" source drift; re-registering ` +
+      `(was ${JSON.stringify(existing)}, want ${JSON.stringify(declaredSource)})`,
+    )
+    await runClaude(["plugin", "marketplace", "remove", name])
+  }
+  const add = await runClaude(["plugin", "marketplace", "add", addPath])
+  if (!add.ok) {
+    console.warn(`[plugins] failed to register marketplace "${name}": ${add.err}`)
+  }
+}
+
+async function ensureExtraMarketplaces(
+  extras: Record<string, { source?: any }> | undefined,
+  loopId: string,
+  km: KnownMarketplacesFile | null,
+): Promise<void> {
+  if (!extras) return
+  for (const [name, entry] of Object.entries(extras)) {
+    const src = entry?.source as any
+    let addPath: string | undefined
+    let normalized: any = src
+    if (typeof src === "string") {
+      addPath = src
+      normalized = { source: "github", repo: src }
+    } else if (src?.source === "directory" && typeof src.path === "string") {
+      addPath = resolvePath(loopClaudeDir(loopId), src.path)
+      normalized = { source: "directory", path: addPath }
+    } else if (src?.source === "github" && typeof src.repo === "string") {
+      addPath = src.repo
+      normalized = { source: "github", repo: src.repo }
+    } else if ((src?.source === "git" || src?.source === "url") && typeof src.url === "string") {
+      addPath = src.url
+      normalized = { source: src.source, url: src.url }
+    }
+    if (!addPath) {
+      console.warn(`[plugins] extraKnownMarketplaces["${name}"]: unsupported source shape, skip`)
+      continue
+    }
+    await ensureMarketplace(name, addPath, normalized, km)
+  }
+}
+
+/**
+ * Install + version-pin check.
+ *
+ * `lockedVersions` maps spec → required version label, sourced from the loop's
+ * snapshot installed_plugins.json (compose merged it from team/profile/personal
+ * tiers). When provided we check the host already has that exact version in
+ * its CC cache; if not, run `claude plugin install` and verify the resulting
+ * version matches.
+ *
+ * Mismatch is loud-failure (option a — see docs/composition.md). The recovery
+ * is for the user to either restore the pinned version manually (e.g. via
+ * marketplace clone checkout dance) or for admin to bump the team lock.
+ * Option b (loopat does the checkout dance automatically) is a future add.
+ *
+ * When `lockedVersions[spec]` is null/undefined: no version pin → fall back to
+ * the old "install if missing" behavior.
+ */
+async function ensurePluginsInstalled(
+  specs: string[],
+  ip: InstalledPluginsFile | null,
+  lockedVersions: Record<string, string | undefined>,
+): Promise<void> {
+  if (specs.length === 0) return
+  const installedKeys = new Set(Object.keys(ip?.plugins ?? {}))
+  for (const spec of specs) {
+    const wantVersion = lockedVersions[spec]
+    const hostEntry = ip?.plugins?.[spec]?.[0]
+    const hostVersion = hostEntry?.version
+
+    if (wantVersion && hostVersion === wantVersion) continue  // pinned + matches
+    if (!wantVersion && installedKeys.has(spec)) continue     // not pinned + installed
+
+    const r = await runClaude(["plugin", "install", spec, "--scope=user"])
+    if (!r.ok) {
+      console.warn(`[plugins] install failed for "${spec}": ${r.err.trim().split("\n").slice(-2).join(" | ")}`)
+      continue
+    }
+
+    // Verify post-install version matches the pin, if there is one.
+    if (wantVersion) {
+      const ip2 = await readJsonOpt<InstalledPluginsFile>(USER_INSTALLED_PLUGINS)
+      const got = ip2?.plugins?.[spec]?.[0]?.version
+      if (got !== wantVersion) {
+        throw new Error(
+          `[plugins] version mismatch for "${spec}": loop pinned "${wantVersion}", ` +
+          `host installed "${got ?? "<unknown>"}".  CC's marketplace clone has likely ` +
+          `advanced past the pinned version. Options:\n` +
+          `  1. Admin: bump the team lock — set this spec's version to "${got ?? "<new>"}" ` +
+          `in knowledge/.loopat/.claude/plugins/installed_plugins.json + git push knowledge.\n` +
+          `  2. Member: restore the pinned version manually — checkout marketplace at the ` +
+          `pinned gitCommitSha, run \`claude plugin install ${spec}\`, then checkout master.`,
+        )
+      }
+    }
+  }
+}
+
+/**
+ * Mtime cache on loops/<id>/.claude/settings.json — we only re-run marketplace
+ * registration + install when compose actually rewrote settings.
+ */
+type EnsureCacheEntry = { mtime: number }
+const ensureCache = new Map<string, EnsureCacheEntry>()
+
+/**
+ * Idempotently ensure the host CC has every marketplace + enabled plugin
+ * installed that the loop's merged settings.json declares. No return value —
+ * the inner SDK resolves enabledPlugins natively at spawn time (via the
+ * wholesale ~/.claude/plugins/ bind in bwrap.ts).
+ */
+export async function ensureLoopPluginsInstalled(loopId: string): Promise<void> {
+  const settingsPath = join(loopClaudeDir(loopId), "settings.json")
+  const mtime = existsSync(settingsPath) ? statSync(settingsPath).mtimeMs : 0
+
+  const cached = ensureCache.get(loopId)
+  if (cached && cached.mtime === mtime) return
+
+  const settings = await readJsonOpt<{
+    enabledPlugins?: Record<string, boolean>
+    extraKnownMarketplaces?: Record<string, { source?: any }>
+  }>(settingsPath)
+
+  const enabled = Object.entries(settings?.enabledPlugins ?? {})
+    .filter(([_, v]) => v)
+    .map(([k]) => k)
+
+  if (enabled.length === 0 && !settings?.extraKnownMarketplaces) {
+    ensureCache.set(loopId, { mtime })
+    return
+  }
+
+  const km = await readJsonOpt<KnownMarketplacesFile>(USER_KNOWN_MARKETPLACES)
+  const ip = await readJsonOpt<InstalledPluginsFile>(USER_INSTALLED_PLUGINS)
+
+  // Read the loop's plugin version lock (compose's merged installed_plugins.json
+  // snapshot). When present, ensurePluginsInstalled enforces the pinned
+  // version per spec; otherwise it falls back to "install if missing".
+  const lockPath = join(loopClaudeDir(loopId), "plugins", "installed_plugins.json")
+  const lock = await readJsonOpt<InstalledPluginsFile>(lockPath)
+  const lockedVersions: Record<string, string | undefined> = {}
+  for (const [spec, entries] of Object.entries(lock?.plugins ?? {})) {
+    lockedVersions[spec] = entries[0]?.version
+  }
+
+  await ensureExtraMarketplaces(settings?.extraKnownMarketplaces, loopId, km)
+  await ensurePluginsInstalled(enabled, ip, lockedVersions)
+
+  ensureCache.set(loopId, { mtime })
+}
+
+/**
+ * Resolve a `name@marketplace` spec to a host path (best-effort, no install
+ * side-effect). Used by:
+ *   - session.ts: pre-seed plugin slash-commands before CC's init payload
+ *   - loop-stats.ts: count plugin contributions for the NewLoopDialog preview
+ *
+ * Prefers the marketplace's local source dir (preserves symlinks); falls back
+ * to the CC cache installPath. Returns null if not installed.
+ */
+export async function lookupPluginInstallPath(spec: string): Promise<string | null> {
+  const ip = await readJsonOpt<InstalledPluginsFile>(USER_INSTALLED_PLUGINS)
+  const km = await readJsonOpt<KnownMarketplacesFile>(USER_KNOWN_MARKETPLACES)
+  if (!ip) return null
+  const entry = ip.plugins?.[spec]?.[0]
+  if (!entry?.installPath) return null
+
+  const atIdx = spec.lastIndexOf("@")
+  if (atIdx >= 0) {
+    const pluginName = spec.slice(0, atIdx)
+    const marketName = spec.slice(atIdx + 1)
+    const market = km?.[marketName]
+    if (market?.installLocation) {
+      const catalog = await readJsonOpt<MarketplaceCatalog>(
+        join(market.installLocation, ".claude-plugin", "marketplace.json"),
+      )
+      const cat = catalog?.plugins?.find((p) => p.name === pluginName)
+      const src = typeof cat?.source === "string" ? cat.source : null
+      if (src?.startsWith("./")) {
+        const p = join(market.installLocation, src)
+        if (existsSync(p)) return p
+      }
+    }
+  }
+  return existsSync(entry.installPath) ? entry.installPath : null
+}