@huynle/hub 0.8.0 → 0.8.2

package/packages/cli/src/profiles-mcp.ts

@@ -0,0 +1,301 @@
+// MCP tools for the profile lifecycle (FX-03, m8sthu85): show a profile and its versions, create one, edit its
+// metadata, write new versions (whole content, a rollback, or one skill or command attached/detached), archive and
+// restore it, and pin a version to a session. The read tools a session uses on its own pin (profile, profile_skill,
+// profile_command) and the listing (profiles, profile_usage) stay in mcp.ts.
+//
+// Profiles are immutable versioned bundles (HWA-14, RP-08): nothing here edits a version. Every content change is
+// POST /profiles/:id/versions with the profile's revision; attaching or detaching a skill or command reads the latest
+// version and writes its content with that one change as the next version (a stale revision answers conflict, so a
+// concurrent change is never overwritten). No server behaviour is added: each tool is one existing route of
+// src/central/profiles/routes.ts (plus the reads it needs).
+//
+// Annotations for gateway review (packages/cli/src/mcp.ts maps them): reads are readOnlyHint; create, metadata edits
+// and new versions only reorganize (destructiveHint false: pinned sessions keep their explicit version, and an old
+// version can be restored with fromVersion); archive/restore (no new versions or pins) and pins (applied to a running
+// session) keep the default destructiveHint. Changes send expectedRevision, so repeating one is idempotent.
+import { sanitizeText } from "../../sdk/src/envelope.ts"
+import { ToolArgError } from "./tool-args"
+import type { Profiles } from "../../sdk/src/client.ts"
+import type { ProfileCommand, ProfileContent, ProfileSkill, ProfileVersionSummary, ProfileView } from "../../sdk/src/types.ts"
+
+type Args = Record<string, unknown>
+
+/** The shape of an MCP tool (as packages/cli/src/mcp.ts registers them). */
+export interface ProfileTool {
+  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 profiles: Profiles }, args: Args, signal: AbortSignal): Promise<string>
+}
+
+const STRING = { type: "string" } as const
+const STRINGS = { type: "array", items: STRING } as const
+const ID = { type: "string", description: "The profile's ID (prof_…; see profiles)." } as const
+const REVISION = { type: "integer", minimum: 0, description: "The profile's revision you read (profile_show); a stale one answers conflict with the current revision." } as const
+const IDEMPOTENCY = { type: "string", description: "Idempotency-Key: the same key and arguments within 24 h answer the first result again." } as const
+const SKILL = { type: "object", properties: { name: { ...STRING, description: "A slug." }, description: STRING, body: { ...STRING, description: "The skill's full text (loaded on demand)." } }, required: ["name", "description", "body"] } as const
+const COMMAND = { type: "object", properties: { name: { ...STRING, description: "A slug." }, description: STRING, template: { ...STRING, description: "Text with {{name}} parameters and {{secret:NAME}} references (never resolved by the hub)." } }, required: ["name", "description", "template"] } as const
+const CONTENT_FIELDS = {
+  instructions: { type: ["string", "null"], description: "The profile's instructions (AGENTS.md-like text)." },
+  model: { type: ["string", "null"], description: "provider/model the profile suggests." },
+  skills: { type: "array", items: SKILL, description: "Skills, wholesale." },
+  commands: { type: "array", items: COMMAND, description: "Commands, wholesale." },
+} as const
+const META_FIELDS = {
+  title: { ...STRING, description: "1–120 characters." },
+  description: STRING,
+  tags: { ...STRINGS, description: "Slugs." },
+  metadata: { type: "object", additionalProperties: STRING, description: "String key/value pairs (≤ 32 slug keys)." },
+  projects: { ...STRINGS, description: "Project names the profile is meant for (≤ 16)." },
+} as const
+const SCOPES = "App tokens need scope profiles:read (reads) or profiles:manage (changes; profile_version_create with content fields and the skill/command set/remove tools read the latest version first, so they also need profiles:read); pins need profiles:assign and sessions:read (an app also needs a prompt grant on the session). Session tokens never change profiles. A profile confers no authority."
+
+/** A bad tool argument: mcp.ts answers it as `invalid: …` (an isError result; tool-args.ts). */
+const ArgError = ToolArgError
+
+const need = (args: Args, key: string): string => {
+  const value = args[key]
+  if (typeof value !== "string" || !value.trim()) throw new ArgError(`"${key}" is required (a non-empty string)`)
+  return value
+}
+const optional = (args: Args, key: string): string | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "string") throw new ArgError(`"${key}" must be a string`)
+  return value.trim() ? value : undefined
+}
+const whole = (args: Args, key: string, min: number, what: string): number => {
+  const value = args[key]
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min) throw new ArgError(`"${key}" is required: ${what}`)
+  return value
+}
+const revision = (args: Args): number => whole(args, "expectedRevision", 0, "the revision you read (profile_show; 0 for a session with no pin)")
+const idempotency = (args: Args) => {
+  const key = optional(args, "idempotencyKey")
+  return key ? { idempotencyKey: key } : {}
+}
+/** The given fields of `keys` (undefined ones dropped). */
+const picked = (args: Args, keys: readonly string[]): Record<string, unknown> => Object.fromEntries(keys.filter((k) => args[k] !== undefined).map((k) => [k, args[k]]))
+
+const one = (text: string) => sanitizeText(text).replace(/\s+/g, " ")
+
+/** `prof_…  name  vN rN  state  title` */
+export const profileLine = (p: ProfileView): string => `${p.id}  ${p.name}  v${p.latestVersion} r${p.revision}  ${p.state}  ${one(p.title)}`
+
+/** A version's contents by name (never bodies). */
+function summaryLines(v: ProfileVersionSummary | undefined): string[] {
+  if (!v) return []
+  return [
+    `version ${v.version} (${v.digest.slice(0, 12)}, ${v.bytes} bytes): instructions ${v.instructions ? "yes" : "no"}${v.model ? `, model ${one(v.model)}` : ""}`,
+    `skills: ${v.skills.length ? v.skills.map((s) => s.name).join(", ") : "none"}`,
+    `commands: ${v.commands.length ? v.commands.map((c) => `${c.name}(${c.params.join(", ")})`).join(", ") : "none"}`,
+    ...(v.secretRefs.length ? [`secret references: ${v.secretRefs.join(", ")}`] : []),
+  ]
+}
+
+const versionText = (r: { profile: ProfileView; version: ProfileVersionSummary }) => [`new version ${r.version.version}: ${profileLine(r.profile)}`, ...summaryLines(r.version)].join("\n")
+
+/** The content of a profile's latest version (what an attach/detach starts from). */
+async function latestContent(profiles: Profiles, id: string, signal: AbortSignal): Promise<{ latest: number; content: ProfileContent }> {
+  const { profile } = await profiles.get(id, { signal })
+  const { version } = await profiles.version(profile.id, profile.latestVersion, { signal })
+  return { latest: version.version, content: version.content }
+}
+
+/** A tool writing the latest version's content with one change as the next version. */
+const contentTool = (
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: readonly string[],
+  change: (content: ProfileContent, args: Args, latest: number) => ProfileContent,
+): ProfileTool => ({
+  name,
+  description: `${description} Writes the latest version's content with this change as the next version (versions are immutable; pinned sessions keep theirs). ${SCOPES}`,
+  properties: { id: ID, ...properties, expectedRevision: REVISION },
+  required: ["id", ...required, "expectedRevision"],
+  readOnly: false,
+  organizes: true,
+  idempotent: true,
+  run: async (hub, args, signal) => {
+    const expectedRevision = revision(args)
+    const id = need(args, "id")
+    const { latest, content } = await latestContent(hub.profiles, id, signal)
+    return versionText(await hub.profiles.createVersion(id, { expectedRevision, content: change(content, args, latest) }, { signal }))
+  },
+})
+
+/** `items` with `item` replacing the one of its name (in place), else appended. */
+const setNamed = <T extends { readonly name: string }>(items: readonly T[], item: T): T[] =>
+  items.some((i) => i.name === item.name) ? items.map((i) => (i.name === item.name ? item : i)) : [...items, item]
+const removeNamed = <T extends { readonly name: string }>(items: readonly T[], name: string, what: string, latest: number): T[] => {
+  if (!items.some((i) => i.name === name)) throw new ArgError(`version ${latest} has no ${what} ${name}`)
+  return items.filter((i) => i.name !== name)
+}
+
+const stateTool = (verb: "archive" | "restore", description: string): ProfileTool => ({
+  name: `profile_${verb}`,
+  description: `${description} ${SCOPES}`,
+  properties: { id: ID, expectedRevision: REVISION },
+  required: ["id", "expectedRevision"],
+  readOnly: false,
+  idempotent: true,
+  run: async (hub, args, signal) => {
+    const expectedRevision = revision(args)
+    const { profile } = await hub.profiles.update(need(args, "id"), { expectedRevision, state: verb === "archive" ? "archived" : "active" }, { signal })
+    return `${verb === "archive" ? "archived" : "restored"}: ${profileLine(profile)}`
+  },
+})
+
+export const profileLifecycleTools: readonly ProfileTool[] = [
+  // ---------- reads ----------
+  {
+    name: "profile_show",
+    description: `One profile: name, title, state, revision (send it as expectedRevision), tags, projects, metadata, and its latest version's instructions, model, skill and command names (never bodies). ${SCOPES}`,
+    properties: { id: ID },
+    required: ["id"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const { profile, latest } = await hub.profiles.get(need(args, "id"), { signal })
+      return [
+        profileLine(profile),
+        ...(profile.description ? [`description: ${one(profile.description)}`] : []),
+        ...(profile.tags?.length ? [`tags: ${profile.tags.join(", ")}`] : []),
+        ...(profile.projects?.length ? [`projects: ${profile.projects.map(one).join(", ")}`] : []),
+        ...(profile.metadata && Object.keys(profile.metadata).length ? [`metadata: ${Object.entries(profile.metadata).map(([k, v]) => `${k}=${one(v)}`).join(", ")}`] : []),
+        ...summaryLines(latest),
+      ].join("\n")
+    },
+  },
+  {
+    name: "profile_versions",
+    description: `A profile's retained versions, newest first (version, digest, bytes, when, skill and command counts). ${SCOPES}`,
+    properties: { id: ID, limit: { type: "integer", minimum: 1, maximum: 200 }, cursor: STRING },
+    required: ["id"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const limit = args.limit === undefined ? undefined : whole(args, "limit", 1, "a whole number from 1 to 200")
+      const cursor = optional(args, "cursor")
+      const page = await hub.profiles.versions(need(args, "id"), { signal, ...(limit !== undefined ? { limit } : {}), ...(cursor ? { cursor } : {}) })
+      const counts = (v: (typeof page.items)[number]) => (v.skills !== undefined ? `  ${v.skills} skills, ${v.commands ?? 0} commands${v.instructions ? ", instructions" : ""}` : "")
+      return [...page.items.map((v) => `v${v.version}  ${v.digest.slice(0, 12)}  ${v.bytes} bytes  ${new Date(v.createdAt).toISOString()}${counts(v)}`), ...(page.cursor ? [`more: cursor ${page.cursor}`] : [])].join("\n") || "no versions"
+    },
+  },
+
+  // ---------- definitions ----------
+  {
+    name: "profile_create",
+    description: `Create a profile: a versioned bundle of instructions, skills and commands, published as version 1 at once. The name is unique per user. Attach it to a team role with team_role_set (profile), pin it with profile_assign. ${SCOPES}`,
+    properties: { name: { ...STRING, description: "A slug, unique per user." }, ...META_FIELDS, ...CONTENT_FIELDS, idempotencyKey: IDEMPOTENCY },
+    required: ["name", "title"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      need(args, "name")
+      need(args, "title")
+      const meta = picked(args, ["name", "title", "description", "tags", "metadata", "projects"]) as { name: string; title: string }
+      const text = Object.entries(picked(args, ["instructions", "model"])).filter(([, v]) => v !== null)
+      const content = { ...Object.fromEntries(text), skills: (args.skills ?? []) as ProfileSkill[], commands: (args.commands ?? []) as ProfileCommand[] } as ProfileContent
+      const r = await hub.profiles.create({ ...meta, content }, { signal, ...idempotency(args) })
+      // A replay of the same idempotencyKey answers the first result again (the API does not mark replays).
+      return [`created: ${profileLine(r.profile)}`, ...summaryLines(r.version)].join("\n")
+    },
+  },
+  {
+    name: "profile_update",
+    description: `Edit a profile's metadata: title, description, tags, metadata, projects (null clears description, metadata or projects). Content changes are new versions (profile_version_create, profile_skill_set, …). ${SCOPES}`,
+    properties: { id: ID, ...META_FIELDS, description: { type: ["string", "null"] }, metadata: { ...META_FIELDS.metadata, type: ["object", "null"] }, projects: { ...META_FIELDS.projects, type: ["array", "null"] }, expectedRevision: REVISION },
+    required: ["id", "expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const patch = picked(args, ["title", "description", "tags", "metadata", "projects"])
+      if (Object.keys(patch).length === 0) throw new ArgError("give at least one field to change")
+      const { profile } = await hub.profiles.update(need(args, "id"), { expectedRevision, ...patch }, { signal })
+      return `updated: ${profileLine(profile)}`
+    },
+  },
+  {
+    name: "profile_version_create",
+    description: `Write a profile's next version: either content fields (instructions, model, skills, commands; the ones you omit are kept from the latest version, null clears instructions or model) or fromVersion (an older version's content again: an explicit rollback). Versions are immutable; pinned sessions keep theirs until re-pinned. ${SCOPES}`,
+    properties: { id: ID, ...CONTENT_FIELDS, fromVersion: { type: "integer", minimum: 1, description: "A retained version to restore as the next one." }, expectedRevision: REVISION, idempotencyKey: IDEMPOTENCY },
+    required: ["id", "expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const id = need(args, "id")
+      const given = Object.keys(picked(args, Object.keys(CONTENT_FIELDS)))
+      const options = { signal, ...idempotency(args) }
+      if (args.fromVersion !== undefined) {
+        if (given.length) throw new ArgError(`give either fromVersion or content fields (${given.join(", ")}), not both`)
+        return versionText(await hub.profiles.createVersion(id, { expectedRevision, fromVersion: whole(args, "fromVersion", 1, "a version number") }, options))
+      }
+      if (!given.length) throw new ArgError("give content fields (instructions, model, skills, commands) or fromVersion")
+      const { content } = await latestContent(hub.profiles, id, signal)
+      const next: Record<string, unknown> = { ...content }
+      for (const key of given) {
+        if (args[key] === null) delete next[key]
+        else next[key] = args[key]
+      }
+      return versionText(await hub.profiles.createVersion(id, { expectedRevision, content: next as unknown as ProfileContent }, options))
+    },
+  },
+  contentTool("profile_skill_set", "Attach a skill to a profile, or replace the skill of that name.", { name: { ...STRING, description: "The skill's name (a slug)." }, description: STRING, body: { ...STRING, description: "The skill's full text." } }, ["name", "description", "body"], (content, args) => ({
+    ...content,
+    skills: setNamed(content.skills, { name: need(args, "name"), description: need(args, "description"), body: need(args, "body") }),
+  })),
+  contentTool("profile_skill_remove", "Detach a skill from a profile.", { name: { ...STRING, description: "The skill's name." } }, ["name"], (content, args, latest) => ({
+    ...content,
+    skills: removeNamed(content.skills, need(args, "name"), "skill", latest),
+  })),
+  contentTool(
+    "profile_command_set",
+    "Attach a command to a profile, or replace the command of that name.",
+    { name: { ...STRING, description: "The command's name (a slug)." }, description: STRING, template: COMMAND.properties.template },
+    ["name", "description", "template"],
+    (content, args) => ({ ...content, commands: setNamed(content.commands, { name: need(args, "name"), description: need(args, "description"), template: need(args, "template") }) }),
+  ),
+  contentTool("profile_command_remove", "Detach a command from a profile.", { name: { ...STRING, description: "The command's name." } }, ["name"], (content, args, latest) => ({
+    ...content,
+    commands: removeNamed(content.commands, need(args, "name"), "command", latest),
+  })),
+  stateTool("archive", "Archive a profile: it takes no new versions or pins; pinned sessions keep theirs; reversible with profile_restore."),
+  stateTool("restore", "Restore an archived profile (it takes versions and pins again)."),
+
+  // ---------- pins ----------
+  {
+    name: "profile_assign",
+    description: `Pin a profile version to a session (applied through its machine; the ack tells whether it took). Send the session's pin revision (0 when it has none; see profile). Pinning confers no authority. ${SCOPES}`,
+    properties: { addr: { ...STRING, description: "The session: @name, ses_… ID or other address." }, profileID: ID, version: { type: "integer", minimum: 1 }, expectedRevision: { ...REVISION, description: "The session's pin revision (0 when it has none)." } },
+    required: ["addr", "profileID", "version", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const { assignment: a } = await hub.profiles.assign(need(args, "addr"), { profileID: need(args, "profileID"), version: whole(args, "version", 1, "a version number"), expectedRevision }, { signal })
+      return `${a.sessionID} pins ${a.profileID} v${a.version} r${a.revision}${a.ack ? `, ack ${a.ack.status}${a.ack.offline ? " (offline)" : ""}` : ""}`
+    },
+  },
+  {
+    name: "profile_unassign",
+    description: `Remove a session's pin (what it already applied stays until it restarts). Send the pin's revision (profile_assign's answer). ${SCOPES}`,
+    properties: { addr: { ...STRING, description: "The session." }, expectedRevision: { ...REVISION, description: "The session's pin revision." } },
+    required: ["addr", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const addr = need(args, "addr")
+      await hub.profiles.unassign(addr, revision(args), { signal })
+      return `unpinned ${addr}`
+    },
+  },
+]

package/packages/cli/src/setup/commands.ts

@@ -56,7 +56,8 @@ import { TxStore } from "../bootstrap/transaction/store.ts"
 import type { TxOutcome } from "../bootstrap/transaction/engine.ts"
 import { readNodeConfig, nodeConfigPath } from "../../../node/src/config.ts"
 import { str, UsageError, type FlagKind, type Parsed } from "../args"
-import { resolveCredentials, type Env } from "../credentials"
+import { resolveCredentials, type Credentials, type Env } from "../credentials"
+import { isInsecureStoredURL, storedInsecureWarning } from "../bootstrap/enrollment/policy.ts"
 import { clientFor } from "../http"
 import { hubLaunchDriver } from "./launch-driver.ts"
 import { errorCodeOf, issuesText, PlanRefusal } from "./contributors.ts"
@@ -214,11 +215,28 @@ function readState(snapshot: DiscoverySnapshot): BootstrapState {
   }
 }
 
+/**
+ * This shell's hub login for the verification launch; a stored plain-http, non-loopback login is warned about once
+ * on stderr, as every `hub` command does.
+ */
+export function launchCredentials(io: Pick<SetupIo, "env" | "home" | "stderr">): () => Credentials | undefined {
+  let warned = false
+  return () => {
+    const found = resolveCredentials(io.env as Env, io.home)
+    if (found?.source === "login" && !warned && isInsecureStoredURL(found.url)) {
+      warned = true
+      io.stderr(`hubctl: warning: ${storedInsecureWarning(found.url)}\n`)
+    }
+    return found
+  }
+}
+
 /** The verification launch over the hub launch API, with this shell's hub login (resolved when it starts). */
 function launchDriverFor(io: SetupIo) {
   const store = credentialStoreFor(io.env, io.home)
+  const login = launchCredentials(io)
   const client = () => {
-    const credentials = resolveCredentials(io.env as Env, io.home)
+    const credentials = login()
     if (!credentials) throw new Error("not logged in to the hub (run `hub login --scope sessions:launch`; an app token launches under a grant with verb launch)")
     return clientFor(credentials)
   }

package/packages/cli/src/spoke-services.ts

@@ -18,7 +18,7 @@ export type ServiceVerb = (typeof SERVICE_VERBS)[number]
 export const isServiceVerb = (verb: string | undefined): verb is ServiceVerb => (SERVICE_VERBS as readonly string[]).includes(verb ?? "")
 
 /** Where config.json and the hub state dir are (shared by every hub spoke). */
-const HUB_PLACES = ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR"] as const
+const HUB_PLACES = ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "XDG_STATE_HOME"] as const
 
 export const CLAUDE_CODE_SERVICE: ServiceSpec = {
   service: "claude-code",

package/packages/cli/src/team-intake-mcp.ts

@@ -5,6 +5,7 @@
 // sessions submit under team policy and, in the team's entry role, report status.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
 import { reportIntakeStatus, TEAM_INTAKE_STATUS_INPUTS, type TeamIntake, type TeamIntakeApi, type TeamIntakePriority, type TeamIntakeStatus, type TeamIntakeStatusInput } from "../../sdk/src/team-intake.ts"
+import { ToolArgError } from "./tool-args"
 
 type Args = Record<string, unknown>
 
@@ -29,24 +30,24 @@ const UPDATES: readonly TeamIntakeStatusInput[] = TEAM_INTAKE_STATUS_INPUTS
 
 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)`)
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
   return value
 }
 const optional = (args: Args, key: string): string | undefined => {
   const value = args[key]
   if (value === undefined || value === null) return undefined
-  if (typeof value !== "string") throw new Error(`"${key}" must be a string`)
+  if (typeof value !== "string") throw new ToolArgError(`"${key}" must be a string`)
   return value.trim() ? value : undefined
 }
 const strings = (args: Args, key: string): string[] | undefined => {
   const value = args[key]
   if (value === undefined || value === null) return undefined
-  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new Error(`"${key}" must be a list of strings`)
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new ToolArgError(`"${key}" must be a list of strings`)
   return value
 }
 const oneOf = <T extends string>(args: Args, key: string, allowed: readonly T[]): T | undefined => {
   const value = optional(args, key)
-  if (value !== undefined && !allowed.includes(value as T)) throw new Error(`"${key}" must be one of ${allowed.join(", ")}`)
+  if (value !== undefined && !allowed.includes(value as T)) throw new ToolArgError(`"${key}" must be one of ${allowed.join(", ")}`)
   return value as T | undefined
 }
 
@@ -55,7 +56,7 @@ function dueOf(args: Args): number | undefined {
   const value = args.due
   if (value === undefined || value === null || value === "") return undefined
   const ms = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN
-  if (!Number.isSafeInteger(ms) || ms <= 0) throw new Error(`"due" must be an ISO date/time or epoch milliseconds`)
+  if (!Number.isSafeInteger(ms) || ms <= 0) throw new ToolArgError(`"due" must be an ISO date/time or epoch milliseconds`)
   return ms
 }
 
@@ -146,10 +147,10 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
     idempotent: true,
     run: async (hub, args, signal) => {
       const status = oneOf(args, "status", UPDATES)
-      if (!status) throw new Error(`"status" is required: one of ${UPDATES.join(", ")}`)
+      if (!status) throw new ToolArgError(`"status" is required: one of ${UPDATES.join(", ")}`)
       const expectedRevision = args.expectedRevision
       if (expectedRevision !== undefined && expectedRevision !== null && (typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0))
-        throw new Error(`"expectedRevision" must be the revision you read (or left out)`)
+        throw new ToolArgError(`"expectedRevision" must be the revision you read (or left out)`)
       const reason = optional(args, "reason")
       const { intake, assignment } = await reportIntakeStatus(hub.teams, need(args, "team"), need(args, "intake"), { status, ...(typeof expectedRevision === "number" ? { expectedRevision } : {}), ...(reason ? { reason } : {}) }, { signal })
       return `${intake.id} is ${intake.status}${intake.progress ? ` (${intake.progress})` : ""}, revision ${intake.revision}${assignment ? `; assignment ${assignment.id} ${assignment.status}` : ""}`

package/packages/cli/src/teams-mcp.ts

@@ -10,6 +10,7 @@
 // the default destructiveHint. Changes of existing records send expectedRevision, so repeating one is idempotent.
 // Decision answers and grant administration stay console-only: there is no tool for them here.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
+import { ToolArgError } from "./tool-args"
 import type { LaunchSpec } from "../../sdk/src/types.ts"
 import type { Team, TeamDraft, TeamEdge, TeamPatch, TeamRole, TeamRoster, Teams, TeamSpec } from "../../sdk/src/teams.ts"
 
@@ -57,9 +58,66 @@ const SPEC_FIELDS = {
   metadata: { type: "object", additionalProperties: STRING, description: "String key/value pairs (keys are slugs)." },
   projects: { ...STRINGS, description: "Project names the team works on." },
 } as const
+// (FX-03, l3vynemo) The launch spec as validateLaunchSpec (src/central/agent/launch-spec.ts) takes it: NESTED sections,
+// unlike the plain launch tool's flat fields. Keep the two in step. No additionalProperties: false, so a flat field
+// reaches the hub, whose answer names the nested place it belongs (a client-side schema refusal would not).
+const LAUNCH = {
+  type: "object",
+  description:
+    "A launch spec (nested, as POST /api/agent/launches takes; unlike the launch tool's flat fields): workspace{repo, mode, branch, base, remote} is required; placement{machine, labels, mode}, runtime{kind, profile}, end{when, timeout, cleanup} and the top-level fields are optional; key is set by staffing (send idempotencyKey instead). The role's prefs fill harness, model and placement.machine, and its profile fills agentProfile, when not given. A flat field (repo, machine, cleanup at the top) is refused with the nested place it belongs.",
+  properties: {
+    workspace: {
+      type: "object",
+      description: "Where the member works on its machine.",
+      properties: {
+        repo: { ...STRING, description: "The repository's absolute path on the machine." },
+        mode: { type: "string", enum: ["worktree", "checkout", "clone"], description: "worktree (default; needs branch), checkout, or clone (needs remote)." },
+        branch: { ...STRING, description: "The branch to create or check out (a safe git branch name; required for worktree)." },
+        base: { ...STRING, description: "What a new branch starts from." },
+        remote: { ...STRING, description: "An https or ssh git remote, without credentials (required for clone)." },
+      },
+      required: ["repo"],
+    },
+    placement: {
+      type: "object",
+      description: "Which machine runs it.",
+      properties: {
+        machine: { ...STRING, description: "A machine ID or name." },
+        labels: { type: "object", additionalProperties: STRING, description: "Node labels to match." },
+        mode: { type: "string", enum: ["require", "prefer"], description: "require (default) or prefer the machine/labels." },
+      },
+    },
+    runtime: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["host", "openshell"], description: "host (default) or openshell (clone workspaces only)." },
+        profile: { ...STRING, description: "An openshell sandbox profile (openshell only)." },
+      },
+    },
+    end: {
+      type: "object",
+      description: "When the launch ends.",
+      properties: {
+        when: { type: "string", enum: ["idle", "asked", "never"], description: "idle (default), asked or never." },
+        timeout: { type: ["string", "number"], description: "1 minute to 30 days: seconds, or 30m, 4h, 2d." },
+        cleanup: { type: "string", enum: ["keep", "remove"], description: "keep (default) or remove the workspace at the end." },
+      },
+    },
+    name: { ...STRING, description: "The session's @name, without the @." },
+    roles: { ...STRINGS, description: "Roles the session claims (up to 10)." },
+    harness: { ...STRING, description: "The harness (default opencode)." },
+    agent: { ...STRING, description: "The harness agent." },
+    model: { ...STRING, description: "provider/model." },
+    prompt: { ...STRING, description: "The first prompt (up to 10000 characters)." },
+    intent: { ...STRING, description: "What the session is for (one line)." },
+    labels: { type: "object", additionalProperties: STRING, description: "Free-form app labels." },
+    agentProfile: { type: "object", properties: { profileID: STRING, version: { type: "integer", minimum: 1 } }, required: ["profileID", "version"], description: "The profile version to pin (needs profiles:assign for an app)." },
+  },
+  required: ["workspace"],
+} as const
 const SCOPES = "App tokens need scope teams:read (reads) or teams:manage (changes); seats, status and staffing also need sessions:read. Session tokens read only teams they are seated in and never change definitions. Team roles confer no authority."
 
-class ArgError extends Error {}
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
@@ -352,7 +410,7 @@ export const teamTools: readonly TeamTool[] = [
   {
     name: "team_staff",
     description: `Staff a role: attach an existing session (sessionID, any machine) or launch a new member (launch: a launch spec as the launch tool takes). An agent needs the user's grants (roles for the session's project; launch for a repo) or the hub answers needs_user; staffing never issues grants. ${SCOPES}`,
-    properties: { team: TEAM, role: STRING, sessionID: { ...STRING, description: "An existing session (ses_…)." }, launch: { type: "object", description: "A launch spec (repo, harness, model, prompt, …)." }, idempotencyKey: IDEMPOTENCY },
+    properties: { team: TEAM, role: STRING, sessionID: { ...STRING, description: "An existing session (ses_…)." }, launch: LAUNCH, idempotencyKey: IDEMPOTENCY },
     required: ["team", "role"],
     readOnly: false,
     run: async (hub, args, signal) => {
@@ -386,7 +444,7 @@ export const teamTools: readonly TeamTool[] = [
   {
     name: "team_replace",
     description: `Replace a seat by an existing session (sessionID) or a new launch (launch): the old seat ends at once and the new member gets the slot's next generation. Send the seat's revision (team_status). ${SCOPES}`,
-    properties: { team: TEAM, staffingID: STRING, sessionID: STRING, launch: { type: "object" }, expectedRevision: { ...REVISION, description: "The seat's revision you read (team_status)." } },
+    properties: { team: TEAM, staffingID: STRING, sessionID: STRING, launch: LAUNCH, expectedRevision: { ...REVISION, description: "The seat's revision you read (team_status)." } },
     required: ["team", "staffingID", "expectedRevision"],
     readOnly: false,
     run: async (hub, args, signal) => {

package/packages/cli/src/tool-args.ts

@@ -0,0 +1,6 @@
+// (R-04) The one error class for a bad MCP tool argument. Every tool family (mcp.ts, teams-mcp.ts,
+// team-intake-mcp.ts, artifacts-mcp.ts, artifact-jobs-mcp.ts, profiles-mcp.ts, watchlist.ts) throws it, and mcp.ts
+// answers it as `invalid: …` (an isError result), never `<tool> failed: …`.
+
+/** A bad tool argument: mcp.ts answers it as `invalid: <message>`. */
+export class ToolArgError extends Error {}

package/packages/cli/src/watchlist.ts

@@ -4,6 +4,7 @@
 // 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"
+import { ToolArgError } from "./tool-args"
 
 type Args = Record<string, unknown>
 
@@ -52,13 +53,13 @@ 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)`)
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${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`)
+  if (typeof value !== "boolean") throw new ToolArgError(`"${key}" must be true or false`)
   return value
 }
 
@@ -92,9 +93,9 @@ export const watchlistTools: readonly WatchlistTool[] = [
     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)`)
+      if (typeof expected !== "number" || !Number.isSafeInteger(expected) || expected < 0) throw new ToolArgError(`"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`)
+      if (unknown.length) throw new ToolArgError(`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 })

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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/paths.ts

@@ -1,12 +1,12 @@
 // Where the Codex spoke looks and keeps its files. It only reads Codex's home (CODEX_HOME, default ~/.codex) to find
 // the shared daemon's socket; its own files live in <hub state dir>/codex (the hub state dir is $HUB_STATE_DIR, else
-// ~/.local/state/hub), a private (0700) directory holding the service's pid file (spoke.pid) and its log.
+// $XDG_STATE_HOME/hub or ~/.local/state/hub), a private (0700) directory holding the service's pid file (spoke.pid) and its log.
 // $HUB_CODEX_DAEMON_SOCKET names another daemon socket, or "off" for none.
 import { chmodSync, lstatSync, mkdirSync, readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { hubEnv, type Env } from "../../../src/env.ts"
-import { APP_DIR, stateBase } from "../../../src/migrate.ts"
+import { resolveHubStateDir } from "../../../src/migrate.ts"
 
 export function codexHome(env: Env = process.env, home: string = homedir()): string {
   return env.CODEX_HOME || path.join(home, ".codex")
@@ -20,7 +20,7 @@ export function daemonSocketPath(env: Env = process.env, home: string = homedir(
 }
 
 export function codexStateDir(env: Env = process.env, home: string = homedir()): string {
-  return path.join(hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR), "codex")
+  return path.join(resolveHubStateDir(env, home).dir, "codex")
 }
 
 export const pidFile = (env: Env = process.env, home: string = homedir()) => path.join(codexStateDir(env, home), "spoke.pid")

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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

@@ -13,7 +13,7 @@
 // `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.
+// workspaceRoots. `opencode.timeoutSeconds` (1–300, default 30) bounds each warm request.
 import { readFileSync } from "node:fs"
 import { homedir, hostname } from "node:os"
 import path from "node:path"
@@ -55,6 +55,8 @@ export interface OpenCodeNodeConfig {
   /** Project directories the background service keeps loaded; absent: recent sessions' projects under workspaceRoots. */
   readonly directories?: readonly string[]
   readonly servers: readonly OpenCodeServerConfig[]
+  /** The warmer's per-request timeout in seconds (1–300; default opencode-warm.ts WARM_TIMEOUT_MS). */
+  readonly timeoutSeconds?: number
 }
 
 /** A foreground `opencode serve` the node keeps warm. */
@@ -205,7 +207,13 @@ function normalizeOpenCode(raw: unknown, problems: string[]): OpenCodeNodeConfig
     problems.push(`opencode.servers: at most ${OPENCODE_SERVERS_MAX} servers; the rest are ignored`)
     servers.length = OPENCODE_SERVERS_MAX
   }
-  return { ...(directories ? { directories } : {}), servers }
+  let timeoutSeconds: number | undefined
+  if (raw.timeoutSeconds !== undefined) {
+    const t = raw.timeoutSeconds
+    if (typeof t === "number" && Number.isInteger(t) && t >= 1 && t <= 300) timeoutSeconds = t
+    else problems.push("opencode.timeoutSeconds must be a whole number of seconds from 1 to 300")
+  }
+  return { ...(directories ? { directories } : {}), servers, ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}) }
 }
 
 function normalizeHarnesses(raw: unknown, problems: string[]): Record<string, boolean> | undefined {