docks-kit 0.15.5 → 0.16.0

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

@@ -6,7 +6,7 @@
  * vocabulary directly.
  */
 import { p } from "./exec"
-import { homedir } from "node:os"
+import { engineHome } from "./harnesses"
 
 import { kitHome } from "../kitHome"
 import { payloadText } from "../payload"
@@ -15,6 +15,7 @@ import type { TerminalLease } from "./logger"
 import type { BunRuntimeState } from "./bun"
 import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
+import { ompNextSteps, ompSummary, ompSync, type OmpState } from "./ompSync"
 import { normalizeManifest, skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
 import { ExitError, parseArgs, parseClaudePlugin, parseCompactWindow, validateModifierFlags } from "./parseArgs"
@@ -81,6 +82,7 @@ export interface Ctx {
   readonly repoDir: string
   readonly home: string
   readonly agentsDir: string
+  readonly interactive: boolean
   dryRun: boolean
   verbose: boolean
   skipBubblewrap: boolean
@@ -106,19 +108,21 @@ export interface Ctx {
   syncClaude: boolean
   syncCodex: boolean
   syncAgents: boolean
+  syncOmp: boolean
   /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
   readonly nextStepTriggers: {
     claudePlugins: boolean
     claudeRestart: boolean
     codexRestart: boolean
     skillsRestart: boolean
+    ompRestart: boolean
   }
 }
 
 /** Globals default from env using the historical ${VAR:-default} contract. */
 function makeCtx(services: EngineServices): Ctx {
   const env = process.env
-  const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir()
+  const home = engineHome(env)
   const compactWindowSource = env["CLAUDE_COMPACT_WINDOW"] ?? ""
   const claudeCompactWindow = compactWindowSource === "" ? "" : parseCompactWindow(compactWindowSource)
   if (claudeCompactWindow === undefined) {
@@ -133,6 +137,11 @@ function makeCtx(services: EngineServices): Ctx {
     repoDir: kitHome(),
     home,
     agentsDir: env["AGENTS_DIR"] !== undefined && env["AGENTS_DIR"] !== "" ? env["AGENTS_DIR"] : p(home, ".agents"),
+    interactive:
+      env["DOCKS_KIT_INTERACTIVE"] === "1" ||
+      (env["DOCKS_KIT_INTERACTIVE"] !== "0" &&
+        process.stdout.isTTY === true &&
+        process.stdin.isTTY === true),
     dryRun: env["DRY_RUN"] === "1",
     verbose: env["DOCKS_KIT_VERBOSE"] === "1",
     skipBubblewrap: env["SKIP_BUBBLEWRAP"] === "1",
@@ -154,7 +163,14 @@ function makeCtx(services: EngineServices): Ctx {
     syncClaude: false,
     syncCodex: false,
     syncAgents: false,
-    nextStepTriggers: { claudePlugins: false, claudeRestart: false, codexRestart: false, skillsRestart: false }
+    syncOmp: false,
+    nextStepTriggers: {
+      claudePlugins: false,
+      claudeRestart: false,
+      codexRestart: false,
+      skillsRestart: false,
+      ompRestart: false
+    }
   }
 }
 
@@ -181,6 +197,7 @@ async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number
     | { readonly kind: "claude"; readonly runtime: ClaudeRuntimeState }
     | { readonly kind: "codex" }
     | { readonly kind: "skills"; readonly state: SkillsState }
+    | { readonly kind: "omp"; readonly state: OmpState }
   interface SelectedPipeline {
     readonly name: string
     readonly run: SyncTask<PipelineResult>
@@ -208,6 +225,12 @@ async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number
       run: async () => ({ kind: "skills", state: await skillsSync(ctx) })
     })
   }
+  if (ctx.syncOmp) {
+    selected.push({
+      name: "omp",
+      run: async () => ({ kind: "omp", state: await ompSync(ctx) })
+    })
+  }
 
   // A populated skills manifest deploys with `-a claude-code codex`, and symlink healing also writes into Claude's tree.
   ctx.syncConcurrency = syncConcurrencyForManifest(
@@ -243,9 +266,11 @@ async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number
   const codexRan = ctx.syncCodex
   let claudeRuntime: ClaudeRuntimeState | undefined
   let skillsState: SkillsState | undefined
+  let ompState: OmpState | undefined
   for (const result of results) {
     if (result.kind === "claude") claudeRuntime = result.runtime
     else if (result.kind === "skills") skillsState = result.state
+    else if (result.kind === "omp") ompState = result.state
   }
 
   echo("")
@@ -254,11 +279,13 @@ async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number
   if (claudeRuntime !== undefined) claudeSummary(ctx, claudeRuntime)
   if (codexRan) codexSummary(ctx)
   if (skillsState !== undefined) skillsSummary(ctx, skillsState)
+  if (ompState !== undefined) ompSummary(ctx, ompState)
 
   const advice = [
     ...(claudeRan ? claudeNextSteps(ctx) : []),
     ...(codexRan ? codexNextSteps(ctx) : []),
-    ...(skillsState !== undefined ? skillsNextSteps(ctx) : [])
+    ...(skillsState !== undefined ? skillsNextSteps(ctx) : []),
+    ...(ompState !== undefined ? ompNextSteps(ctx) : [])
   ]
   if (advice.length > 0) {
     echo("")

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

@@ -0,0 +1,101 @@
+/**
+ * omp path resolution, mirroring upstream `packages/utils/src/dirs.ts`
+ * `DirResolver`. The kit deploys into two different roots and must not guess
+ * either one: the agent directory holds `AGENTS.md`, `config.yml`, and
+ * `mcp.json`; the data root holds `marketplaces.json` and `plugins/`.
+ *
+ * Resolution reads the environment and probes directory existence only, so a
+ * dry run stays free of omp subcommands.
+ */
+import { existsSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+
+import { p } from "./exec"
+
+/** Upstream CONFIG_DIR_NAME; PI_CONFIG_DIR renames this directory under home. */
+const DEFAULT_CONFIG_DIR_NAME = ".omp"
+/** Upstream APP_NAME, the fixed segment under an XDG category root. */
+const APP_NAME = "omp"
+/** Upstream PROFILE_NAME_RE. An invalid name degrades to the default profile. */
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/
+/** Windows device aliases upstream rejects, bare or with any extension. */
+const WINDOWS_RESERVED_BASENAME_RE = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/i
+
+export interface OmpPaths {
+  /** undefined for the default profile, else the normalized profile name */
+  readonly profile: string | undefined
+  /** config root for the active profile */
+  readonly configRoot: string
+  /** directory holding AGENTS.md, config.yml, mcp.json - never XDG-redirected */
+  readonly agentDir: string
+  /** root holding marketplaces.json and plugins/ - XDG-redirected when adopted */
+  readonly dataRoot: string
+}
+
+export interface OmpPathInputs {
+  readonly home: string
+  readonly env: Record<string, string | undefined>
+  readonly platform: NodeJS.Platform
+}
+
+/**
+ * Upstream `normalizeProfileName`, minus the throw: an invalid value reaches
+ * `readProfileFromEnvSafe`, which degrades to the default profile so a bad env
+ * var cannot crash a bare import.
+ */
+function normalizeProfile(value: string | undefined): string | undefined {
+  const name = value?.trim()
+  if (name === undefined || name === "" || name === "default") return undefined
+  if (name === "." || name === ".." || name.endsWith(".")) return undefined
+  if (!PROFILE_NAME_RE.test(name) || WINDOWS_RESERVED_BASENAME_RE.test(name)) return undefined
+  return name
+}
+
+/** Upstream applies `path.resolve` to PI_CODING_AGENT_DIR, so cwd anchors a relative value. */
+function resolveAgentOverride(value: string): string {
+  return isAbsolute(value) ? value : resolve(process.cwd(), value)
+}
+
+export function ompPaths({ home, env, platform }: OmpPathInputs): OmpPaths {
+  // OMP_PROFILE wins whenever it is defined, including when explicitly empty;
+  // PI_PROFILE is only the legacy fallback.
+  const profile = normalizeProfile(env["OMP_PROFILE"] !== undefined ? env["OMP_PROFILE"] : env["PI_PROFILE"])
+
+  // PI_CONFIG_DIR is a config root dirname joined under home, not a path.
+  const configDirName = env["PI_CONFIG_DIR"]
+  const baseRoot = p(home, configDirName !== undefined && configDirName !== "" ? configDirName : DEFAULT_CONFIG_DIR_NAME)
+  const configRoot = profile === undefined ? baseRoot : p(baseRoot, "profiles", profile)
+
+  // A named profile derives its own agent directory and ignores the override.
+  const agentOverride = env["PI_CODING_AGENT_DIR"]
+  const defaultAgentDir = p(configRoot, "agent")
+  const agentDir = profile === undefined && agentOverride !== undefined && agentOverride !== ""
+    ? resolveAgentOverride(agentOverride)
+    : defaultAgentDir
+
+  return { profile, configRoot, agentDir, dataRoot: xdgDataRoot(env, platform, profile, agentDir === defaultAgentDir) ?? configRoot }
+}
+
+/**
+ * XDG is a Linux and macOS convention upstream disables whenever an agent-dir
+ * override is active, and adopts a category only once its omp directory
+ * exists - `omp config init-xdg` creates it without moving existing data. A
+ * named profile keys on its own `profiles/<name>` path and adopts that path,
+ * so a profile stays where it was first activated.
+ */
+function xdgDataRoot(
+  env: Record<string, string | undefined>,
+  platform: NodeJS.Platform,
+  profile: string | undefined,
+  agentDirIsDefault: boolean
+): string | undefined {
+  if (!agentDirIsDefault) return undefined
+  if (platform !== "linux" && platform !== "darwin") return undefined
+
+  const dataHome = env["XDG_DATA_HOME"]
+  if (dataHome === undefined || dataHome === "") return undefined
+
+  const appRoot = p(dataHome, APP_NAME)
+  const candidate = profile === undefined ? appRoot : p(appRoot, "profiles", profile)
+  return existsSync(candidate) ? candidate : undefined
+}

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

@@ -0,0 +1,421 @@
+/**
+ * EngineNative `sync omp` pipeline. config.yml merges through mergeOmpConfig
+ * because omp serialises that file itself. Paths come from ompPaths because
+ * profiles, PI_CONFIG_DIR, PI_CODING_AGENT_DIR, and XDG roots each move them.
+ * Resolution stays within the environment and filesystem probes so no omp
+ * subcommand runs under ctx.dryRun.
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+
+import { payloadDisplayPath, payloadText, type PayloadPath } from "../payload"
+import { bunBootstrap } from "./bun"
+import { commandExists, p, spawnProcess, type AsyncProcessResult } from "./exec"
+import type { Ctx } from "./index"
+import { isObject, parseJson } from "./jq"
+import { ompPaths } from "./ompPaths"
+import { mergeOmpConfig } from "./ompYaml"
+import { field } from "./toolchain"
+
+const MARKETPLACE_NAME = "docks"
+const MARKETPLACE_SOURCE = "https://github.com/DocksDocks/docks.git"
+const MARKETPLACE_PLUGIN_IDS = ["docks@docks", "plan-lifecycle@docks"] as const
+type OmpTextPayloadPath = Extract<PayloadPath, `SoT/.omp/${string}`>
+
+export interface OmpState {
+  readonly pluginsInstalled: number
+}
+
+export async function ompSync(ctx: Ctx): Promise<OmpState> {
+  await bunBootstrap(ctx, ctx.services)
+
+  const paths = ompPaths({ home: ctx.home, env: process.env, platform: ctx.services.platform.raw() })
+  const agentDir = paths.agentDir
+  if (!ctx.dryRun) ensureDirectory(agentDir)
+
+  syncWholeFile(ctx, "SoT/.omp/AGENTS.md", p(agentDir, "AGENTS.md"), "omp AGENTS.md already in sync", "omp AGENTS.md synced")
+  syncWholeFile(ctx, "SoT/.omp/mcp.json", p(agentDir, "mcp.json"), "omp mcp.json already in sync", "omp mcp.json synced")
+  syncConfig(ctx, p(agentDir, "config.yml"))
+
+  const intercomRootSetting = process.env["PI_CODING_AGENT_DIR"]
+  const intercomRoot = intercomRootSetting !== undefined && intercomRootSetting !== ""
+    ? isAbsolute(intercomRootSetting)
+      ? intercomRootSetting
+      : resolve(process.cwd(), intercomRootSetting)
+    : p(ctx.home, ".pi", "agent")
+  const intercomDir = p(intercomRoot, "intercom")
+  if (!ctx.dryRun) ensureDirectory(intercomDir)
+  syncWholeFile(
+    ctx,
+    "SoT/.omp/intercom.json",
+    p(intercomDir, "config.json"),
+    "omp intercom configuration already in sync",
+    "omp intercom configuration synced"
+  )
+
+  const legacyRegistryFile = paths.dataRoot === paths.configRoot
+    ? undefined
+    : p(paths.configRoot, "marketplaces.json")
+  await syncMarketplace(ctx, p(paths.dataRoot, "marketplaces.json"), legacyRegistryFile)
+  const pluginsInstalled = await syncPlugins(ctx)
+  return { pluginsInstalled }
+}
+
+// ------------------------------------------------------------ file modes ----
+
+/**
+ * `mkdirSync` and `writeFileSync` apply their `mode` only when they create the
+ * path, so an existing world-readable directory or file would keep its mode.
+ * The explicit chmod reproduces `install -d -m 0700` / `install -m 0600`.
+ */
+function ensureDirectory(directory: string): void {
+  mkdirSync(directory, { recursive: true, mode: 0o700 })
+  chmodSync(directory, 0o700)
+}
+
+function writePrivateFile(target: string, content: string): void {
+  writeFileSync(target, content, { mode: 0o600 })
+  chmodSync(target, 0o600)
+}
+
+function backupPrivateFile(target: string): void {
+  copyFileSync(target, `${target}.bak`)
+  chmodSync(`${target}.bak`, 0o600)
+}
+
+// --------------------------------------------------------------- config ----
+
+function syncWholeFile(
+  ctx: Ctx,
+  sourcePath: OmpTextPayloadPath,
+  target: string,
+  alreadyMessage: string,
+  syncedMessage: string
+): void {
+  const { change, echo, verbose } = ctx.services.logger
+  const source = payloadDisplayPath(sourcePath)
+  const content = payloadText(sourcePath)
+
+  if (ctx.dryRun) {
+    echo(`[dry-run] cp ${source} -> ${target}`)
+    return
+  }
+
+  if (existsSync(target) && readFileSync(target, "utf8") === content) {
+    verbose(alreadyMessage)
+    return
+  }
+  if (existsSync(target)) backupPrivateFile(target)
+  writePrivateFile(target, content)
+  change(syncedMessage)
+  ctx.nextStepTriggers.ompRestart = true
+}
+
+function syncConfig(ctx: Ctx, target: string): void {
+  const { change, echo, verbose } = ctx.services.logger
+  const source = payloadDisplayPath("SoT/.omp/config.yml")
+  const sotText = payloadText("SoT/.omp/config.yml")
+
+  if (!existsSync(target)) {
+    if (ctx.dryRun) {
+      echo(`[dry-run] cp ${source} -> ${target}`)
+      return
+    }
+    writePrivateFile(target, sotText)
+    change("omp config.yml installed")
+    ctx.nextStepTriggers.ompRestart = true
+    return
+  }
+
+  const deployedText = readFileSync(target, "utf8")
+  const merged = mergeOmpConfig(sotText, deployedText)
+  if (merged === deployedText) {
+    verbose("omp config.yml already in sync")
+    return
+  }
+  if (ctx.dryRun) {
+    echo(`[dry-run] merge ${source} -> ${target} (backup at ${target}.bak)`)
+    return
+  }
+
+  backupPrivateFile(target)
+  writePrivateFile(`${target}.tmp`, merged)
+  renameSync(`${target}.tmp`, target)
+  chmodSync(target, 0o600)
+  change("omp config.yml merged (backup at config.yml.bak)")
+  ctx.nextStepTriggers.ompRestart = true
+}
+
+// ---------------------------------------------------------- marketplace ----
+
+function registryHasDocks(registryFile: string): boolean {
+  if (!existsSync(registryFile)) return false
+
+  let registryText: string
+  try {
+    registryText = readFileSync(registryFile, "utf8")
+  } catch {
+    return false
+  }
+  const registry = parseJson(registryText)
+  if (registry === undefined) return false
+  if (isObject(registry) && Object.hasOwn(registry, MARKETPLACE_NAME)) return true
+
+  const entries = Array.isArray(registry)
+    ? registry
+    : isObject(registry) && Array.isArray(registry["marketplaces"])
+      ? registry["marketplaces"]
+      : []
+  return entries.some((entry) => isObject(entry) && entry["name"] === MARKETPLACE_NAME)
+}
+
+function firstOutputLine(result: AsyncProcessResult): string {
+  const output = `${result.stdout}${result.stderr}`
+  return output.split("\n")[0] || "unknown error"
+}
+
+/**
+ * Three states, because upstream `getMarketplacesRegistryPath` copies a legacy
+ * `configRoot` registry forward the first time it resolves an XDG data root:
+ * the active registry lists docks, only the legacy registry lists it, or
+ * neither does. In the middle state the kit never copies user data itself; it
+ * takes the refresh path, whose own resolution inside omp performs that
+ * adoption and leaves the active registry present.
+ */
+async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFile?: string): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
+  const registered = registryHasDocks(registryFile)
+  const adoptable = !registered && legacyRegistryFile !== undefined && registryHasDocks(legacyRegistryFile)
+
+  if (ctx.dryRun) {
+    if (adoptable) {
+      echo(
+        ctx.skipPluginRefresh === true
+          ? "[dry-run] omp plugin marketplace list"
+          : `[dry-run] omp plugin marketplace update ${MARKETPLACE_NAME}`
+      )
+    } else if (registered) verbose("omp docks marketplace already registered")
+    else echo(`[dry-run] omp plugin marketplace add ${MARKETPLACE_SOURCE}`)
+    return
+  }
+
+  if (!registered && !adoptable) {
+    progress("Registering omp docks marketplace...")
+    const result = await spawnProcess("omp", ["plugin", "marketplace", "add", MARKETPLACE_SOURCE], {
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+    clearProgress()
+    if (result.error === undefined && result.exitCode === 0) {
+      change("omp docks marketplace registered")
+    } else {
+      warn(
+        `omp docks marketplace registration failed: ${firstOutputLine(result)}; run manually: omp plugin marketplace add ${MARKETPLACE_SOURCE}`
+      )
+    }
+    return
+  }
+
+  if (ctx.skipPluginRefresh === true) {
+    if (!adoptable) {
+      verbose("omp docks marketplace already registered; refresh-only update skipped")
+      return
+    }
+
+    // Adoption only needs omp to resolve the registry path. `marketplace list`
+    // does that and fetches nothing, so it stays inside the flag's contract
+    // while leaving the active registry present.
+    progress("Adopting omp docks marketplace registry...")
+    const listed = await spawnProcess("omp", ["plugin", "marketplace", "list"], {
+      stdio: ["ignore", "ignore", "pipe"]
+    })
+    clearProgress()
+    if (listed.error === undefined && listed.exitCode === 0) {
+      change("omp docks marketplace registry adopted; refresh-only update skipped")
+    } else {
+      warn(
+        `omp docks marketplace adoption failed: ${firstOutputLine(listed)}; run manually: omp plugin marketplace list`
+      )
+    }
+    return
+  }
+
+  progress("Updating omp docks marketplace...")
+  const result = await spawnProcess("omp", ["plugin", "marketplace", "update", MARKETPLACE_NAME], {
+    stdio: ["ignore", "pipe", "pipe"]
+  })
+  clearProgress()
+  if (result.error === undefined && result.exitCode === 0) {
+    verbose("omp docks marketplace refreshed")
+  } else {
+    warn(
+      `omp docks marketplace update failed: ${firstOutputLine(result)}; run manually: omp plugin marketplace update ${MARKETPLACE_NAME}`
+    )
+  }
+}
+
+// -------------------------------------------------------------- plugins ----
+
+interface InstalledPlugins {
+  readonly marketplace: Set<string>
+  readonly npm: Map<string, string>
+}
+
+async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
+  const result = await spawnProcess("omp", ["plugin", "list", "--json"], {
+    stdio: ["ignore", "pipe", "ignore"]
+  })
+  if (result.error !== undefined || result.exitCode !== 0) return undefined
+
+  const value = parseJson(result.stdout)
+  if (
+    value === undefined ||
+    !isObject(value) ||
+    !Array.isArray(value["marketplace"]) ||
+    !Array.isArray(value["npm"])
+  ) {
+    return undefined
+  }
+
+  // `omp plugin list --json` reports marketplace rows as
+  // `{ id: "<plugin>@<marketplace>", scope, entries: [...] }` - the composite id
+  // is already the token `omp plugin install/upgrade` takes. omp emits one row
+  // per scope holding the plugin, so a match found only in a `project` row
+  // means the user scope is empty and `upgrade --scope user` would fail; only a
+  // `user` row counts as installed for this pipeline.
+  const marketplace = new Set<string>()
+  for (const row of value["marketplace"]) {
+    if (!isObject(row) || typeof row["id"] !== "string" || row["scope"] !== "user") continue
+    marketplace.add(row["id"])
+  }
+
+  const npm = new Map<string, string>()
+  for (const row of value["npm"]) {
+    if (!isObject(row) || typeof row["name"] !== "string" || typeof row["version"] !== "string") continue
+    npm.set(row["name"], row["version"])
+  }
+  return { marketplace, npm }
+}
+
+async function runPluginCommand(
+  ctx: Ctx,
+  plugin: string,
+  args: ReadonlyArray<string>
+): Promise<boolean> {
+  const { clearProgress, progress, warn } = ctx.services.logger
+  progress(`Updating omp plugin ${plugin}...`)
+  const result = await spawnProcess("omp", args, { stdio: ["ignore", "pipe", "pipe"] })
+  clearProgress()
+  if (result.error === undefined && result.exitCode === 0) return true
+
+  warn(
+    `omp plugin operation failed for ${plugin}: ${firstOutputLine(result)}; run manually: omp ${args.join(" ")}`
+  )
+  return false
+}
+
+async function syncPlugins(ctx: Ctx): Promise<number> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
+
+  if (ctx.dryRun) {
+    const piIntercomPin = field(ctx, "pi-intercom", "verified")
+    for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
+      echo(`[dry-run] omp plugin install --scope user ${pluginId}`)
+    }
+    if (piIntercomPin === "") {
+      warn("pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin")
+    } else {
+      echo(`[dry-run] omp install pi-intercom@${piIntercomPin}`)
+    }
+    return 0
+  }
+
+  if (ctx.services.deps.probe("omp").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "omp",
+      ctx.services.logger,
+      "deployed omp config only — marketplace and plugin passes skipped; re-run sync after installing"
+    )
+    return 0
+  }
+  if (ctx.services.deps.probe("git").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "git",
+      ctx.services.logger,
+      "plugin marketplaces are git repos — omp plugin refresh skipped; re-run sync after installing"
+    )
+    return 0
+  }
+  const piIntercomPin = field(ctx, "pi-intercom", "verified")
+
+  progress("Checking installed omp plugins...")
+  const installed = await installedPluginIdsFromCli()
+  clearProgress()
+  if (installed === undefined) {
+    warn("omp plugin inventory unavailable — falling back to the full refresh path")
+  }
+
+  let pluginsInstalled = installed === undefined
+    ? 0
+    : MARKETPLACE_PLUGIN_IDS.filter((pluginId) => installed.marketplace.has(pluginId)).length +
+      (piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0)
+  let operationsSucceeded = 0
+
+  for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
+    const present = installed?.marketplace.has(pluginId) === true
+    if (present && ctx.skipPluginRefresh === true) {
+      verbose(`omp plugin ${pluginId} already installed; refresh-only update skipped`)
+      continue
+    }
+
+    const args = present
+      ? ["plugin", "upgrade", "--scope", "user", pluginId]
+      : ["plugin", "install", "--scope", "user", pluginId]
+    if (await runPluginCommand(ctx, pluginId, args)) {
+      operationsSucceeded++
+      if (!present) pluginsInstalled++
+    }
+  }
+
+  if (piIntercomPin === "") {
+    warn("pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin")
+  } else {
+    const installedVersion = installed?.npm.get("pi-intercom")
+    const present = installedVersion !== undefined
+    if (installedVersion === piIntercomPin) {
+      verbose(`omp npm plugin pi-intercom already installed at ${piIntercomPin}`)
+    } else if (present && ctx.skipPluginRefresh === true) {
+      verbose("omp npm plugin pi-intercom already installed; refresh-only update skipped")
+    } else {
+      const args = present
+        ? ["install", "--force", `pi-intercom@${piIntercomPin}`]
+        : ["install", `pi-intercom@${piIntercomPin}`]
+      if (await runPluginCommand(ctx, "pi-intercom", args)) {
+        operationsSucceeded++
+        if (!present) pluginsInstalled++
+      }
+    }
+  }
+
+  if (operationsSucceeded > 0) {
+    change(`omp plugins synced (plugins: ~${operationsSucceeded})`)
+    ctx.nextStepTriggers.ompRestart = true
+  } else {
+    verbose("omp plugins already in sync")
+  }
+  return pluginsInstalled
+}
+
+// -------------------------------------------------------------- summary ----
+
+export function ompSummary(ctx: Ctx, state: OmpState): void {
+  const { echo } = ctx.services.logger
+  const agentDir = ompPaths({ home: ctx.home, env: process.env, platform: ctx.services.platform.raw() }).agentDir
+  echo(`omp:      ${agentDir}`)
+  if (!ctx.dryRun) echo(`omp plugins: ${state.pluginsInstalled} installed`)
+}
+
+export function ompNextSteps(ctx: Ctx): Array<string> {
+  return ctx.verbose || ctx.nextStepTriggers.ompRestart
+    ? ["Restart omp to load any refreshed plugins, skills, or tools."]
+    : []
+}