@huynle/hub 0.7.4 → 0.8.0

package/packages/cli/src/watchlist.ts

@@ -0,0 +1,135 @@
+// `hub watchlist [show|watch|unwatch|mute|unmute] <addr>` and the MCP tools watchlist_get, watchlist_update,
+// watchlist_watch and watchlist_mute (CON-01): the Concierge's watchlist over /api/agent/concierge/watchlist. Users and
+// app tokens (sessions:read to show, sessions:manage to change); the user's current Concierge session through its
+// act token (show and the verbs). Other session tokens get not found (exit 3).
+import { sanitizeLabel } from "../../sdk/src/envelope.ts"
+import type { Concierge, WatchlistChanged, WatchlistConfig, WatchlistUpdate, WatchlistView } from "../../sdk/src/index.ts"
+
+type Args = Record<string, unknown>
+
+/** The shape of an MCP tool (as packages/cli/src/mcp.ts registers them). */
+export interface WatchlistTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  readonly idempotent?: boolean
+  run(hub: { readonly concierge: Concierge }, args: Args, signal: AbortSignal): Promise<string>
+}
+
+/** One value from the hub, safe to print: escapes, control, bidi and zero-width characters removed, one line. */
+const safe = (value: unknown) => sanitizeLabel(String(value), 1024)
+const list = (items: readonly string[]) => (items.length ? items.map(safe).join(", ") : "none")
+
+export function watchlistConfigText(c: WatchlistConfig): string {
+  return [
+    `revision ${safe(c.revision)}`,
+    `auto-active: ${c.autoActive ? `on (within ${safe(c.activeWithinHours)} h)` : "off"}  pins: ${c.usePins ? "on" : "off"}`,
+    `sessions: ${list(c.sessions)}`,
+    `projects: ${list(c.projects)}`,
+    `labels: ${c.labels.length ? c.labels.map((l) => Object.entries(l).map(([k, v]) => `${safe(k)}=${safe(v)}`).join(",")).join("; ") : "none"}`,
+    `muted: ${list(c.muted)}`,
+    `muted projects: ${list(c.mutedProjects)}`,
+  ].join("\n")
+}
+
+export function watchlistText(view: WatchlistView): string {
+  const rows = view.entries.map((e) => `${safe(e.sessionID)}  ${e.reasons.map(safe).join(",")}${e.lastActiveAt !== undefined ? `  active ${new Date(e.lastActiveAt).toISOString()}` : ""}`)
+  return [watchlistConfigText(view.config), "", view.entries.length ? `watching ${view.entries.length}${view.truncated ? " (truncated)" : ""}:` : "watching nothing", ...rows].join("\n")
+}
+
+export function watchlistChangedText(verb: string, r: WatchlistChanged): string {
+  return `${r.changed ? `${verb}` : `already ${verb}`}: ${safe(r.sessionID)} (revision ${safe(r.config.revision)})`
+}
+
+const PAST: Record<string, string> = { watch: "watching", unwatch: "not watching", mute: "muted", unmute: "unmuted" }
+export const watchlistVerbText = (verb: "watch" | "unwatch" | "mute" | "unmute", r: WatchlistChanged) => watchlistChangedText(PAST[verb]!, r)
+
+const ADDR = { type: "string", description: "Session address: ses_… (or a unique prefix), @name, @@role, @name.project." } as const
+const STRINGS = { type: "array", items: { type: "string" } } as const
+
+const need = (args: Args, key: string): string => {
+  const value = args[key]
+  if (typeof value !== "string" || !value.trim()) throw new Error(`"${key}" is required (a non-empty string)`)
+  return value
+}
+const flag = (args: Args, key: string, fallback: boolean): boolean => {
+  const value = args[key]
+  if (value === undefined || value === null) return fallback
+  if (typeof value !== "boolean") throw new Error(`"${key}" must be true or false`)
+  return value
+}
+
+const UPDATE_FIELDS = ["autoActive", "activeWithinHours", "usePins", "sessions", "projects", "labels", "muted", "mutedProjects"] as const
+
+export const watchlistTools: readonly WatchlistTool[] = [
+  {
+    name: "watchlist_get",
+    description: "The Concierge's watchlist: its config (revision) and the sessions it watches now, with why (active, pinned, pinned_project, explicit, project, label). Needs sessions:read for an app token.",
+    properties: {},
+    readOnly: true,
+    run: async (hub, _args, signal) => watchlistText(await hub.concierge.watchlist.get({ signal })),
+  },
+  {
+    name: "watchlist_update",
+    description:
+      "Change the watchlist config under the revision you read (expectedRevision; a stale one is a conflict). Give only the fields to change: autoActive, activeWithinHours (1–24), usePins, sessions (ses_… IDs), projects (absolute dirs), labels ([{key: value}]), muted, mutedProjects. Users and app tokens with sessions:manage.",
+    properties: {
+      expectedRevision: { type: "integer", minimum: 0 },
+      autoActive: { type: "boolean" },
+      activeWithinHours: { type: "integer", minimum: 1, maximum: 24 },
+      usePins: { type: "boolean" },
+      sessions: STRINGS,
+      projects: STRINGS,
+      labels: { type: "array", items: { type: "object", additionalProperties: { type: "string" } } },
+      muted: STRINGS,
+      mutedProjects: STRINGS,
+    },
+    required: ["expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    run: async (hub, args, signal) => {
+      const expected = args.expectedRevision
+      if (typeof expected !== "number" || !Number.isSafeInteger(expected) || expected < 0) throw new Error(`"expectedRevision" is required (the revision you read)`)
+      const unknown = Object.keys(args).filter((k) => k !== "expectedRevision" && !(UPDATE_FIELDS as readonly string[]).includes(k))
+      if (unknown.length) throw new Error(`Unknown argument${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${safe(k).slice(0, 40)}"`).join(", ")}: use ${UPDATE_FIELDS.join(", ")} and expectedRevision`)
+      const patch: Record<string, unknown> = {}
+      for (const field of UPDATE_FIELDS) if (args[field] !== undefined && args[field] !== null) patch[field] = args[field]
+      const r = await hub.concierge.watchlist.update(patch as WatchlistUpdate, expected, { signal })
+      const head = r.config.revision === expected ? `No change (revision ${safe(expected)})` : `Updated the watchlist (revision ${safe(expected)} → ${safe(r.config.revision)})`
+      return `${head}\n${watchlistConfigText(r.config)}`
+    },
+  },
+  {
+    name: "watchlist_watch",
+    description: "Watch a session (watch: false stops watching it). A subagent watches its root. Idempotent; grants nothing.",
+    properties: { addr: ADDR, watch: { type: "boolean", description: "Default true; false unwatches." } },
+    required: ["addr"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const on = flag(args, "watch", true)
+      const addr = need(args, "addr")
+      const r = on ? await hub.concierge.watchlist.watch(addr, { signal }) : await hub.concierge.watchlist.unwatch(addr, { signal })
+      return watchlistVerbText(on ? "watch" : "unwatch", r)
+    },
+  },
+  {
+    name: "watchlist_mute",
+    description: "Mute a session in the watchlist (mute: false unmutes it): a muted session is never watched, whatever includes it. Not a notification mute. Idempotent.",
+    properties: { addr: ADDR, mute: { type: "boolean", description: "Default true; false unmutes." } },
+    required: ["addr"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const on = flag(args, "mute", true)
+      const addr = need(args, "addr")
+      const r = on ? await hub.concierge.watchlist.mute(addr, { signal }) : await hub.concierge.watchlist.unmute(addr, { signal })
+      return watchlistVerbText(on ? "mute" : "unmute", r)
+    },
+  },
+]

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/codex/src/profile.ts

@@ -0,0 +1,163 @@
+// Profile application for Codex threads (HWA-18; protocol packages/protocol/src/profiles.ts, SDK ProfileApplyHandler).
+// What a hub profile can and cannot become in a running Codex thread, without touching Codex's own files:
+//
+// - instructions: applied live. The framed block (profileInstructionsBlock: after local instructions, which win)
+//   goes into the thread's context as one developer message through thread/inject_items (no turn is started).
+// - skills: partial. Codex loads native skills only from its configuration (CODEX_HOME/skills, the project's
+//   .codex/skills or .agents/skills), which the spoke never writes. The profile's skills become session-scoped files
+//   in the spoke's private state directory (<dir>/<sessionID>/v<version>-<digest>/skills/<name>/SKILL.md, 0700),
+//   listed by name, description and path in the same context message; a local skill of the same name wins.
+// - commands: not applied (Codex custom prompts live in its global configuration, and the spoke cannot render a
+//   command when the user invokes it there), so `{{secret:NAME}}` references are never resolved here.
+// - model: ignored with a note (a thread's model is chosen at launch; the spoke does not switch it).
+// - launch agent: Codex has no agents; a create with `agent` stays refused (sessions.ts), profiles do not change that.
+//
+// Applies to one session run one at a time; a repeated digest answers the same result (ProfileApplyHandler). When
+// the session is deleted its files go; when the spoke only stops reporting it, they stay (the thread's context still
+// names them) and a later apply rewrites them.
+import { randomBytes } from "node:crypto"
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import type { ProfileApplyRequest, ProfileApplyResult, ProfileSkill } from "../../protocol/src/index.ts"
+import { ProfileApplyHandler, type ProfileApplyOutcome, type ProfileCapabilities, type ProfilePlan } from "../../spoke-sdk/src/index.ts"
+import { ensurePrivateDir } from "./paths.ts"
+
+/** What the Codex spoke can apply of a profile to a running thread (its effective capabilities). */
+export const CODEX_PROFILE_CAPABILITIES: ProfileCapabilities = Object.freeze({
+  instructions: true,
+  skills: true,
+  commands: false,
+  model: false,
+  live: true,
+  renderAtInvocation: false,
+})
+
+export const SKILLS_NOTE =
+  "skills offered as session files listed in the thread context, not native Codex skills (Codex loads those only from its own configuration, which the spoke never writes)"
+
+/** What CodexProfiles needs of the sessions (CodexSessions). */
+export interface CodexProfilePort {
+  /** The thread's working directory, or undefined when the spoke does not report the session. */
+  directory(sessionID: string): string | undefined
+  /** Adds `text` to the thread's context (a developer message; no turn). */
+  inject(sessionID: string, text: string): Promise<void>
+}
+
+export interface CodexProfilesOptions {
+  readonly port: CodexProfilePort
+  /** The spoke's private directory for session-scoped profile files (e.g. <hub state dir>/codex/profiles). */
+  readonly dir: string
+  /** CODEX_HOME, read only: its skills win over the profile's. */
+  readonly codexHome: string
+  readonly log?: (line: string) => void
+}
+
+const LOCAL_NAMES_MAX = 1000
+const SAFE_NAME = /^[A-Za-z0-9_-]{1,100}$/
+
+/** The names of the local Codex skills a thread in `cwd` sees (directory names; read only, bounded). */
+export function localCodexSkillNames(codexHome: string, cwd: string): string[] {
+  const names = new Set<string>()
+  for (const dir of [path.join(codexHome, "skills"), path.join(cwd, ".codex", "skills"), path.join(cwd, ".agents", "skills")]) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries.slice(0, LOCAL_NAMES_MAX)) if (entry.isDirectory() || entry.isSymbolicLink()) names.add(entry.name)
+  }
+  return [...names]
+}
+
+const skillFile = (skill: ProfileSkill) => `---\nname: ${skill.name}\ndescription: ${JSON.stringify(skill.description)}\n---\n\n${skill.body}\n`
+
+export class CodexProfiles {
+  readonly #port: CodexProfilePort
+  readonly #dir: string
+  readonly #codexHome: string
+  readonly #handler: ProfileApplyHandler
+  /** The running apply per session (one at a time). */
+  readonly #chains = new Map<string, Promise<unknown>>()
+
+  constructor(options: CodexProfilesOptions) {
+    this.#port = options.port
+    this.#dir = options.dir
+    this.#codexHome = options.codexHome
+    this.#handler = new ProfileApplyHandler({
+      capabilities: CODEX_PROFILE_CAPABILITIES,
+      local: (sessionID) => {
+        const cwd = this.#port.directory(sessionID)
+        return cwd === undefined ? undefined : { skills: localCodexSkillNames(this.#codexHome, cwd) }
+      },
+      apply: (plan, req) => this.#apply(plan, req),
+    })
+  }
+
+  /** The `profileApply` op handler. */
+  readonly handle = (req: ProfileApplyRequest): Promise<ProfileApplyResult> => {
+    const previous = this.#chains.get(req.sessionID) ?? Promise.resolve()
+    const run = previous.then(() => this.#handler.handle(req))
+    const settled = run.catch(() => {})
+    this.#chains.set(req.sessionID, settled)
+    void settled.then(() => {
+      if (this.#chains.get(req.sessionID) === settled) this.#chains.delete(req.sessionID)
+    })
+    return run
+  }
+
+  /** The spoke no longer reports the session: a later apply applies again (its files stay). */
+  ended(sessionID: string): void {
+    this.#handler.forget(sessionID)
+  }
+
+  /** The session was deleted: forget it and remove its files. */
+  deleted(sessionID: string): void {
+    this.#handler.forget(sessionID)
+    if (SAFE_NAME.test(sessionID)) rmSync(path.join(this.#dir, sessionID), { recursive: true, force: true })
+  }
+
+  async #apply(plan: ProfilePlan, req: ProfileApplyRequest): Promise<ProfileApplyOutcome> {
+    if (this.#port.directory(req.sessionID) === undefined || !SAFE_NAME.test(req.sessionID)) throw new Error(`Unknown Codex session ${req.sessionID}`)
+    const sessionDir = path.join(this.#dir, req.sessionID)
+    const versionName = `v${req.version}-${req.digest.slice(0, 16)}`
+    const versionDir = path.join(sessionDir, versionName)
+    let wrote = false
+    const parts: string[] = []
+    if (plan.instructions !== undefined) parts.push(plan.instructions)
+    if (plan.skills.length) {
+      if (!existsSync(versionDir)) {
+        ensurePrivateDir(this.#dir)
+        mkdirSync(sessionDir, { recursive: true, mode: 0o700 })
+        const temp = path.join(sessionDir, `.tmp-${randomBytes(6).toString("hex")}`)
+        try {
+          for (const skill of plan.skills) {
+            mkdirSync(path.join(temp, "skills", skill.name), { recursive: true, mode: 0o700 })
+            writeFileSync(path.join(temp, "skills", skill.name, "SKILL.md"), skillFile(skill), { mode: 0o600 })
+          }
+          renameSync(temp, versionDir)
+        } catch (cause) {
+          rmSync(temp, { recursive: true, force: true })
+          throw cause
+        }
+        wrote = true
+      }
+      parts.push(
+        [
+          `Skills from hub profile ${req.profileID} version ${req.version} (session-scoped files, not native Codex skills; a local skill of the same name takes precedence). Read a skill's file before you use it:`,
+          ...plan.skills.map((s) => `- ${s.name}: ${s.description} (${path.join(versionDir, "skills", s.name, "SKILL.md")})`),
+        ].join("\n"),
+      )
+    }
+    if (parts.length) {
+      try {
+        await this.#port.inject(req.sessionID, parts.join("\n\n"))
+      } catch (cause) {
+        if (wrote) rmSync(versionDir, { recursive: true, force: true })
+        throw cause
+      }
+    }
+    if (existsSync(sessionDir)) for (const name of readdirSync(sessionDir)) if (name !== versionName || !plan.skills.length) rmSync(path.join(sessionDir, name), { recursive: true, force: true })
+    return plan.skills.length ? { status: "partial", notes: [SKILLS_NOTE] } : {}
+  }
+}

package/packages/codex/src/sessions.ts

@@ -222,6 +222,18 @@ export class CodexSessions {
     return id !== undefined && this.#threads.has(id)
   }
 
+  /** The working directory of a session the spoke reports, else undefined. */
+  directory(sessionID: string): string | undefined {
+    const id = codexThreadID(sessionID)
+    return id === undefined ? undefined : this.#threads.get(id)?.cwd
+  }
+
+  /** Adds `text` to a session's context as a developer message (thread/inject_items: no turn starts). */
+  async injectContext(sessionID: string, text: string): Promise<void> {
+    const thread = this.#thread(sessionID)
+    await thread.conn.request("thread/inject_items", { threadId: thread.id, items: [{ type: "message", role: "developer", content: [{ type: "input_text", text }] }] })
+  }
+
   /** Whether the spoke reports this thread (on any connection). */
   hasThread(threadID: string): boolean {
     return this.#threads.has(threadID.toLowerCase())

package/packages/codex/src/spoke.ts

@@ -10,9 +10,12 @@
 //   never starts the daemon: it connects when the socket answers and tries again every pollMs when it does not.
 //
 // Nothing here writes Codex's files (CODEX_HOME): configuration goes in as -c overrides (codexArgs) and environment.
+import path from "node:path"
 import { HarnessSpoke, type HarnessSpokeOptions } from "../../spoke-sdk/src/index.ts"
 import { openAppServer, type AppServerConnection } from "./app-server.ts"
 import type { RpcID } from "./jsonrpc.ts"
+import { codexHome, codexStateDir } from "./paths.ts"
+import { CodexProfiles } from "./profile.ts"
 import { CodexSessions, type ThreadDescription } from "./sessions.ts"
 import { spawnStdioChannel } from "./stdio.ts"
 import { connectUnixWebSocket } from "./websocket.ts"
@@ -45,6 +48,9 @@ export interface CodexSpokeOptions {
   readonly pollMs?: number
   readonly threadDefaults?: Readonly<Record<string, unknown>>
   readonly turnTimeoutMs?: number
+  /** Session-scoped profile files (default <hub state dir>/codex/profiles) and CODEX_HOME (read only), from env. */
+  readonly profileDir?: string
+  readonly codexHome?: string
   readonly log?: (line: string) => void
   readonly socket?: HarnessSpokeOptions["socket"]
   readonly backoff?: HarnessSpokeOptions["backoff"]
@@ -71,13 +77,24 @@ export function startCodexSpoke(options: CodexSpokeOptions): CodexSpoke {
   const resuming = new Set<string>()
 
   const sessions: CodexSessions = new CodexSessions({
-    spoke: { upsertSession: (info) => spoke.upsertSession(info), endSession: (id) => spoke.endSession(id), emit: (event) => spoke.emit(event) },
+    spoke: {
+      upsertSession: (info) => spoke.upsertSession(info),
+      endSession: (id) => (profiles.ended(id), spoke.endSession(id)),
+      emit: (event) => (event.type === "session.deleted" && profiles.deleted(event.data.sessionID), spoke.emit(event)),
+    },
     createServer: () => ownServer(),
     ...(options.threadDefaults ? { threadDefaults: options.threadDefaults } : {}),
     ...(options.turnTimeoutMs !== undefined ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
     log,
   })
 
+  const profiles = new CodexProfiles({
+    port: { directory: (id) => sessions.directory(id), inject: (id, text) => sessions.injectContext(id, text) },
+    dir: options.profileDir ?? path.join(codexStateDir(options.env), "profiles"),
+    codexHome: options.codexHome ?? codexHome(options.env),
+    log,
+  })
+
   const spoke = new HarnessSpoke({
     server: options.server,
     token: options.token,
@@ -95,6 +112,7 @@ export function startCodexSpoke(options: CodexSpokeOptions): CodexSpoke {
       stop: (req) => sessions.stop(req),
       permission: (req) => sessions.permission(req),
       create: (req) => sessions.create(req),
+      profileApply: profiles.handle,
     },
     deliver: (req) => sessions.deliver(req),
     features: ["hubPrompt", "launch", "turnEvents"],

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/node/src/config.ts

@@ -6,18 +6,27 @@
 // node.json: { "workspaceRoots": ["/Users/huy/projects"], "labels": {"gpu": "no"}, "slots": 6, "memoryMB": 49152,
 //   "openshell": { "enabled": true, "gateway": "openshell", "image": "ghcr.io/huynle/hub-sandbox:0.1",
 //                  "profiles": { "untrusted-code": { "providers": ["anthropic"] } } },
-//   "harnesses": { "claude-code": false } }
+//   "harnesses": { "claude-code": false },
+//   "opencode": { "directories": ["/Users/huy/projects/app"],
+//                 "servers": [{ "url": "http://127.0.0.1:4297", "passwordFile": "/Users/huy/.config/opencode-4297.pw" }] } }
 // `harnesses` overrides what the host runtime detects (harnesses.ts): true offers a harness, false withholds it.
+// `opencode` (RF-04, opencode-warm.ts): foreground `opencode serve` processes to keep warm besides the background
+// service (loopback URLs only, the password from a private file), and the project directories to keep loaded on the
+// service (`directories`) or on a server (its own `directories`); absent: the projects of recent sessions under
+// workspaceRoots.
 import { readFileSync } from "node:fs"
 import { homedir, hostname } from "node:os"
 import path from "node:path"
 import { isAbsolutePath, labelsProblem, NODE_ROOTS_MAX, NODE_SLOTS_MAX } from "../../protocol/src/index.ts"
 import { normalizeOpenShellProfiles, type OpenShellProfiles } from "../../runtime-openshell/src/profiles.ts"
 import { configPath, readConfig } from "../../../src/config.ts"
+import { WARM_DIRECTORIES_MAX } from "./opencode-warm.ts"
 
 type Env = Readonly<Record<string, string | undefined>>
 
 export const NODE_CONFIG_FILE = "node.json"
+/** Foreground OpenCode servers node.json may list. */
+export const OPENCODE_SERVERS_MAX = 8
 /** Concurrent launches when node.json sets no `slots`. */
 export const DEFAULT_SLOTS = 4
 const MEMORY_MB_MAX = 2 ** 31
@@ -37,6 +46,25 @@ export interface NodeConfig {
   readonly openshell?: OpenShellNodeConfig
   /** Per-harness overrides of detection (true: offer it, false: withhold it); absent: detection alone. */
   readonly harnesses?: Readonly<Record<string, boolean>>
+  /** OpenCode servers to keep warm besides the background service, and project directories to keep loaded. */
+  readonly opencode?: OpenCodeNodeConfig
+}
+
+/** node.json `opencode`. */
+export interface OpenCodeNodeConfig {
+  /** Project directories the background service keeps loaded; absent: recent sessions' projects under workspaceRoots. */
+  readonly directories?: readonly string[]
+  readonly servers: readonly OpenCodeServerConfig[]
+}
+
+/** A foreground `opencode serve` the node keeps warm. */
+export interface OpenCodeServerConfig {
+  /** Its origin: http(s) on 127.0.0.1, [::1] or localhost, without user info, path or query. */
+  readonly url: string
+  /** Absolute path of a private file (mode 600) holding its password (OPENCODE_PASSWORD), read on every tick. */
+  readonly passwordFile: string
+  /** Project directories it keeps loaded; absent: recent sessions' projects under workspaceRoots. */
+  readonly directories?: readonly string[]
 }
 
 /** node.json `openshell`: whether the node offers sandboxes, through which gateway, with which image and profiles. */
@@ -107,13 +135,79 @@ export function normalizeNodeConfig(raw: unknown): NodeConfigResult {
 
   const openshell = r.openshell === undefined ? undefined : normalizeOpenShell(r.openshell, problems)
   const harnesses = r.harnesses === undefined ? undefined : normalizeHarnesses(r.harnesses, problems)
+  const opencode = r.opencode === undefined ? undefined : normalizeOpenCode(r.opencode, problems)
 
   return {
-    config: { workspaceRoots, labels, slots, ...(memoryMB !== undefined ? { memoryMB } : {}), ...(openshell ? { openshell } : {}), ...(harnesses ? { harnesses } : {}) },
+    config: { workspaceRoots, labels, slots, ...(memoryMB !== undefined ? { memoryMB } : {}), ...(openshell ? { openshell } : {}), ...(harnesses ? { harnesses } : {}), ...(opencode ? { opencode } : {}) },
     problems,
   }
 }
 
+/** Absolute directories (not /), trailing slashes dropped, at most WARM_DIRECTORIES_MAX; undefined for a non-list. */
+function normalizeDirectories(raw: unknown, field: string, problems: string[]): string[] | undefined {
+  if (!Array.isArray(raw)) {
+    problems.push(`${field} must be a list of absolute paths`)
+    return undefined
+  }
+  const out: string[] = []
+  for (const dir of raw) {
+    if (!isAbsolutePath(dir) || dir === "/") {
+      problems.push(`${field}: ${show(dir)} is not an absolute path (without . or .. segments, and not /)`)
+      continue
+    }
+    const clean = dir.replace(/\/+$/, "")
+    if (!out.includes(clean)) out.push(clean)
+  }
+  if (out.length > WARM_DIRECTORIES_MAX) {
+    problems.push(`${field}: at most ${WARM_DIRECTORIES_MAX} directories; the rest are ignored`)
+    out.length = WARM_DIRECTORIES_MAX
+  }
+  return out
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"])
+
+/** A server URL's origin, or undefined; never echoed in problems (it could carry a password). */
+function loopbackOrigin(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || raw.length > 2048) return undefined
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    return undefined
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return undefined
+  if (url.username || url.password || !LOOPBACK_HOSTS.has(url.hostname)) return undefined
+  if ((url.pathname !== "/" && url.pathname !== "") || url.search || url.hash) return undefined
+  return url.origin
+}
+
+function normalizeOpenCode(raw: unknown, problems: string[]): OpenCodeNodeConfig | undefined {
+  if (!isObject(raw)) {
+    problems.push("opencode must be an object")
+    return undefined
+  }
+  const directories = raw.directories === undefined ? undefined : normalizeDirectories(raw.directories, "opencode.directories", problems)
+  const servers: OpenCodeServerConfig[] = []
+  if (raw.servers !== undefined && !Array.isArray(raw.servers)) problems.push("opencode.servers must be a list of {url, passwordFile, directories?}")
+  const list = Array.isArray(raw.servers) ? raw.servers : []
+  list.forEach((entry, i) => {
+    const field = `opencode.servers[${i}]`
+    if (!isObject(entry)) return void problems.push(`${field} must be an object {url, passwordFile, directories?}`)
+    const url = loopbackOrigin(entry.url)
+    if (!url) return void problems.push(`${field}.url must be an http(s) URL on 127.0.0.1, [::1] or localhost, without user info, path or query`)
+    if (!isAbsolutePath(entry.passwordFile) || entry.passwordFile === "/") return void problems.push(`${field}.passwordFile must be the absolute path of a private (chmod 600) file holding the server's password`)
+    if (servers.some((s) => s.url === url)) return void problems.push(`${field}: ${url} is listed twice; the first one is used`)
+    const dirs = entry.directories === undefined ? undefined : normalizeDirectories(entry.directories, `${field}.directories`, problems)
+    servers.push({ url, passwordFile: entry.passwordFile, ...(dirs ? { directories: dirs } : {}) })
+  })
+  if (servers.length > OPENCODE_SERVERS_MAX) {
+    problems.push(`opencode.servers: at most ${OPENCODE_SERVERS_MAX} servers; the rest are ignored`)
+    servers.length = OPENCODE_SERVERS_MAX
+  }
+  return { ...(directories ? { directories } : {}), servers }
+}
+
 function normalizeHarnesses(raw: unknown, problems: string[]): Record<string, boolean> | undefined {
   if (!isObject(raw)) {
     problems.push("harnesses must be an object of harness names to true or false")