@huynle/hub 0.8.0 → 0.8.1

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/cli/src/bootstrap/adapters/node-services/render.ts

@@ -31,8 +31,8 @@ import { EMBEDDED_TEXT } from "../../release/assets.ts"
 /** The settings each service may carry into its unit (as `hub <service> install` carries them today). */
 export const SERVICE_ENVIRONMENT: Readonly<Record<ServiceID, readonly string[]>> = Object.freeze({
   node: ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_CLAUDE_BIN", "HUB_CODEX_BIN"],
-  "claude-code": ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "HUB_CLAUDE_SOCKET", "HUB_CLAUDE_BIN"],
-  "codex-spoke": ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "CODEX_HOME", "HUB_CODEX_BIN", "HUB_CODEX_DAEMON_SOCKET"],
+  "claude-code": ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "XDG_STATE_HOME", "HUB_CLAUDE_SOCKET", "HUB_CLAUDE_BIN"],
+  "codex-spoke": ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "XDG_STATE_HOME", "CODEX_HOME", "HUB_CODEX_BIN", "HUB_CODEX_DAEMON_SOCKET"],
 })
 
 /** The named root each manager's units live in. */

package/packages/cli/src/bootstrap/discovery/host.ts

@@ -2,6 +2,8 @@
 // container kind. Everything is read through the probe; nothing is executed.
 import { ROOT_IDS, type ContainerKind, type Libc, type RootID, type RootMapping } from "../contracts/index.ts"
 import type { DiscoveryProbe } from "./probe.ts"
+import path from "node:path"
+import { resolveHubStateDir } from "../../../../../src/migrate.ts"
 import { decode, join, normalizeAbs, oneLine } from "./util.ts"
 
 // ---------- roots ----------
@@ -14,7 +16,7 @@ export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined
   const paths: Partial<Record<RootID, string>> = {
     home,
     config,
-    state: xdg("XDG_STATE_HOME", ".local/state"),
+    state: hubStateRoot(probe, home) ?? xdg("XDG_STATE_HOME", ".local/state"),
     data: xdg("XDG_DATA_HOME", ".local/share"),
     "user-bin": join(home, ".local/bin"),
     "system-bin": "/usr/local/bin",
@@ -24,6 +26,18 @@ export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined
   return ROOT_IDS.flatMap((id) => (paths[id] ? [{ id, path: paths[id]! }] : []))
 }
 
+/**
+ * The state root: the parent of the hub state dir (resolveHubStateDir, src/migrate.ts, asked through the probe), so
+ * setup's <state>/hub/bootstrap lands in the dir the hub uses. Undefined (the XDG default) when that dir is not named
+ * "hub" (a custom HUB_STATE_DIR): the plan's paths are <state>/hub/….
+ */
+function hubStateRoot(probe: DiscoveryProbe, home: string): string | undefined {
+  const env = { ...probe.env, ...(probe.env.XDG_STATE_HOME !== undefined ? { XDG_STATE_HOME: normalizeAbs(probe.env.XDG_STATE_HOME) } : {}) }
+  const { dir } = resolveHubStateDir(env, home, (p) => probe.lstat(p) !== "missing")
+  const abs = normalizeAbs(dir)
+  return abs && path.posix.basename(abs) === "hub" ? path.posix.dirname(abs) : undefined
+}
+
 export interface Mount {
   readonly root: string
   readonly point: string

package/packages/cli/src/bootstrap/discovery/probe.ts

@@ -19,7 +19,7 @@ export interface DiscoveryProbe {
   /** The user's home directory (os.homedir()). */
   readonly home: string
   readonly hostname: string
-  /** Read, never recorded: discovery looks at PATH, HOME, XDG_* and `container` only. */
+  /** Read, never recorded: discovery looks at PATH, HOME, XDG_*, HUB_STATE_DIR and `container` only. */
   readonly env: Readonly<Record<string, string | undefined>>
   /** The runtime running this script, when hubctl runs as a script (absent for a standalone binary). */
   readonly runtime?: RuntimeFact

package/packages/cli/src/bootstrap/enrollment/enroll.ts

@@ -18,7 +18,7 @@ import { hostname } from "node:os"
 import type { EnrollStart } from "../../../../protocol/src/index.ts"
 import { EnrollmentRefused, pollEnrollment, startEnrollment } from "../../../../spoke-sdk/src/enroll.ts"
 import type { CredentialStore, MachineCredential, MachineEnrollment } from "../contracts/index.ts"
-import { approvalURL, checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isLoopbackServer, isPlainHTTP, isUserCode } from "./policy.ts"
+import { approvalURL, checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isLoopbackServer, isPlainHTTP, isUserCode, shownURL } from "./policy.ts"
 import { failure, line, success, type MachineResult } from "./result.ts"
 import { CredentialStoreError, type SharingMode, type StoreContents } from "./store.ts"
 import { probeCredential, statusOf, storeFailure } from "./status.ts"
@@ -133,8 +133,8 @@ export async function machineEnroll(options: MachineEnrollOptions): Promise<Mach
   const server = checkServerURL(options.server, allow)
   if (!server) {
     const why = insecureHTTPRefusal(options.server, allow)
-    if (why) return failure(COMMAND, "usage", `${why[0]!.toUpperCase()}${why.slice(1)}: ${line(String(options.server), 200)}`)
-    return failure(COMMAND, "usage", `The hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${line(String(options.server), 200)}`)
+    if (why) return failure(COMMAND, "usage", `${why[0]!.toUpperCase()}${why.slice(1)}: ${line(shownURL(String(options.server)), 200)}`)
+    return failure(COMMAND, "usage", `The hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${line(shownURL(String(options.server)), 200)}`)
   }
   const insecure = isPlainHTTP(server) && !isLoopbackServer(server) ? insecureHTTPWarning(server) : undefined
   const machineName = options.machineName ?? defaultMachineName(hostname())

package/packages/cli/src/bootstrap/enrollment/policy.ts

@@ -165,3 +165,16 @@ export function storedInsecureWarning(value: string): string {
   } catch {}
   return `the stored hub URL ${shown} is plain http: your app token and everything this command sends or receives travel unencrypted on the network; log in again with an https URL (hub login --url https://<hub>)`
 }
+
+/**
+ * A URL as typed, for a refusal message, at most 200 characters: anything before an `@` in its authority-looking
+ * part (user info: a password or token) is replaced by ***. The authority starts after an http(s) scheme or any
+ * scheme followed by slashes or backslashes (`http:u:p@h`, `http:/u:p@h`, `http:\\u:p@h`), else at the start
+ * (`user:pass@h`), and ends at the first /, \\, ? or #. Leading whitespace is dropped.
+ */
+export function shownURL(value: string): string {
+  return value
+    .trimStart()
+    .replace(/^((?:https?:|[a-z][a-z0-9+.-]*:(?=[\/\\]))?[\/\\]*)[^\/\\?#]*@/i, "$1***@")
+    .slice(0, 200)
+}

package/packages/cli/src/cli.ts

@@ -8,7 +8,7 @@ import { loginFile, readLogin, removeLogin, resolveCredentials, writeLogin, type
 import { atName, logText, whoamiText, type Actor, roleText, sessionsText, showText, statusText, whoText } from "./format"
 import { CliError, EXIT, withHub } from "./http"
 import { deviceLogin, promptText, scopeNotes } from "./login"
-import { checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isInsecureStoredURL, isLoopbackServer, isPlainHTTP, storedInsecureWarning } from "./bootstrap/enrollment/policy.ts"
+import { checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isInsecureStoredURL, isLoopbackServer, isPlainHTTP, shownURL, storedInsecureWarning } from "./bootstrap/enrollment/policy.ts"
 import { defaultMachineName } from "./bootstrap/enrollment/enroll.ts"
 import { readSpokeCredentials } from "../../node/src/config.ts"
 import { hostname } from "node:os"
@@ -211,7 +211,7 @@ Options: --json (raw responses), --help, --version
 Addresses: ses_… (or an unambiguous prefix), @name, @@role, @@role#team (quote it: '@@dev#team'), @name.project, @me (the user)
 Credentials: HUB_URL + HUB_SESSION_TOKEN (set in a session's shells), else the \`hub login\` file.
 Exit codes: 0 ok, 1 other, 2 usage, 3 not found/ambiguous/taken, 4 needs user, 5 forbidden/paused,
-  6 rate limited, 7 unsupported/offline, 8 gone, 9 unauthorized/expired`
+  6 rate limited, 7 unsupported/offline/busy, 8 gone, 9 unauthorized/expired`
 
 interface Context {
   readonly io: Io
@@ -707,7 +707,7 @@ const COMMANDS: Record<string, Command> = {
         const server = checkServerURL(url, allow)
         if (!server) {
           const why = insecureHTTPRefusal(url, allow)
-          throw new UsageError(why ? `${why}: ${url.slice(0, 200)}` : `the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${url.slice(0, 200)}`)
+          throw new UsageError(why ? `${why}: ${shownURL(url)}` : `the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${shownURL(url)}`)
         }
         if (isPlainHTTP(server) && !isLoopbackServer(server)) io.stderr(`hub: warning: ${insecureHTTPWarning(server)}\n`)
         token = (given !== undefined && given !== "-" ? given : io.stdin ? await io.stdin() : "").trim()

package/packages/cli/src/http.ts

@@ -31,6 +31,7 @@ const EXIT_OF: Record<string, number> = {
   rate_limited: EXIT.rateLimited,
   unsupported: EXIT.unavailable,
   offline: EXIT.unavailable,
+  busy: EXIT.unavailable,
   gone: EXIT.gone,
   unauthorized: EXIT.unauthorized,
   token_expired: EXIT.unauthorized,

package/packages/cli/src/launches.ts

@@ -121,10 +121,15 @@ export function launchedText(launch: LaunchView, created: boolean, key: string |
 
 export const stoppedLaunchText = (launch: LaunchView): string => `stopped ${summary(launch)}`
 
-/** `lch_1  running  @api ses_1  /repo (branch)  app=brain` */
+/** The app token that launched it: `app "label"` or `app <token id>`. */
+const launcherText = (l: LaunchView) => (l.byLabel ? `app ${JSON.stringify(l.byLabel)}` : `app ${l.by?.replace(/^app:/, "") ?? "?"}`)
+
+/** `lch_1  running  @api ses_1  /repo (branch)  app=brain`; a queued one says why it waits, a revoked launcher is flagged. */
 export function launchLine(l: LaunchView): string {
   const where = l.directory ?? `${l.spec.workspace.repo}${l.spec.workspace.branch ? ` (${l.spec.workspace.branch})` : ""}`
-  return [l.id, stateText(l), sessionText(l) || undefined, where, labelsText(l.spec.labels) || undefined].filter(Boolean).join("  ")
+  const waits = l.state === "queued" && l.waiting ? `waits: ${l.waiting.reason}` : undefined
+  const revoked = l.launcherRevoked && l.state !== "ended" ? `launcher revoked (${launcherText(l)}): stop it with hub launches stop ${l.id}` : undefined
+  return [l.id, stateText(l), sessionText(l) || undefined, where, labelsText(l.spec.labels) || undefined, waits, revoked].filter(Boolean).join("  ")
 }
 
 export const launchesText = (launches: readonly LaunchView[]): string => (launches.length ? launches.map(launchLine).join("\n") : "no launches")
@@ -149,7 +154,8 @@ export function launchText(l: LaunchView): string {
   const run = [l.spec.harness, l.spec.agent, l.spec.model, l.spec.runtime ? `${l.spec.runtime.kind}${l.spec.runtime.profile ? `/${l.spec.runtime.profile}` : ""}` : undefined].filter(Boolean)
   if (run.length) lines.push(`runs: ${run.join(" ")}`)
   if (l.spec.end) lines.push(`ends: ${[l.spec.end.when, l.spec.end.timeout ? `timeout ${l.spec.end.timeout}` : undefined, l.spec.end.cleanup ? `cleanup ${l.spec.end.cleanup}` : undefined].filter(Boolean).join(", ")}`)
-  if (l.by) lines.push(`by: ${l.by}`)
+  if (l.state === "queued" && l.waiting) lines.push(`waits (${l.waiting.wait}) since ${new Date(l.waiting.since).toISOString()}: ${l.waiting.reason}`)
+  if (l.by) lines.push(`by: ${l.by}${l.byLabel ? ` (${l.byLabel})` : ""}${l.launcherRevoked ? ", launcher revoked" : ""}`)
   if (labelsText(l.spec.labels)) lines.push(`labels: ${labelsText(l.spec.labels)}`)
   if (l.artifacts && artifactsText(l.artifacts)) lines.push(`artifacts: ${artifactsText(l.artifacts)}`)
   if (l.history?.length) lines.push("steps:", ...l.history.map(stepText))

package/packages/cli/src/login.ts

@@ -10,7 +10,7 @@
 // - The wait is bounded by the hub's expiry and by maxWaitMs; `signal` cancels it.
 // - The token is returned to the caller only, never printed. A poll that fails in transit is retried until the
 //   deadline (a reply lost after the hub handed the token out cannot be fetched again: the user revokes that token).
-import { approvalURL, checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isLoopbackServer, isPlainHTTP, isUserCode } from "./bootstrap/enrollment/policy.ts"
+import { approvalURL, checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isLoopbackServer, isPlainHTTP, isUserCode, shownURL } from "./bootstrap/enrollment/policy.ts"
 import { UsageError } from "./args"
 import { CliError, EXIT } from "./http"
 
@@ -101,7 +101,7 @@ export async function deviceLogin(options: DeviceLoginOptions): Promise<DeviceLo
   const server = checkServerURL(options.server, allow)
   if (!server) {
     const why = insecureHTTPRefusal(options.server, allow)
-    throw new UsageError(why ? `${why}: ${String(options.server).slice(0, 200)}` : `the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${String(options.server).slice(0, 200)}`)
+    throw new UsageError(why ? `${why}: ${shownURL(String(options.server))}` : `the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${shownURL(String(options.server))}`)
   }
   const insecure = isPlainHTTP(server) && !isLoopbackServer(server) ? insecureHTTPWarning(server) : undefined
   const fetcher = options.fetch ?? fetch

package/packages/cli/src/mcp.ts

@@ -8,7 +8,9 @@
 // artifact_job_cancel; scope artifacts:ai: packages/cli/src/artifact-jobs-mcp.ts), and team intake
 // (team_submit, team_intake, team_intake_update; scope teams:submit: packages/cli/src/team-intake-mcp.ts), and teams
 // (teams, team_show, team_status, team_create, team_publish, team_staff, …; scopes teams:read|manage: teams-mcp.ts),
-// and the Concierge watchlist (watchlist_get, watchlist_update, watchlist_watch, watchlist_mute: watchlist.ts).
+// the profile lifecycle (profile_show, profile_create, profile_update, profile_version_create, profile_skill_set, …,
+// profile_assign; scopes profiles:read|manage|assign: profiles-mcp.ts), and the Concierge watchlist (watchlist_get,
+// watchlist_update, watchlist_watch, watchlist_mute: watchlist.ts).
 import { renderEnvelope, sanitizeText, WAIT_POLL_MAX_S, type AgentMessage, type Asked, type DecisionState, type FormAnswer, type HubClient, type LaunchSpec, type LaunchState, type PromptDelivery, type Inbox, type Sent, type SentAll } from "../../sdk/src/index.ts"
 import { answeredText, approvedText, DELIVERIES, deniedText, needsUserLines, promptedText, stoppedText } from "./acting"
 import { UsageError } from "./args"
@@ -24,6 +26,7 @@ import { artifactTools } from "./artifacts-mcp"
 import { artifactJobTools } from "./artifact-jobs-mcp"
 import { teamIntakeTools } from "./team-intake-mcp"
 import { teamTools } from "./teams-mcp"
+import { ProfileArgError, profileLifecycleTools } from "./profiles-mcp"
 import { watchlistTools } from "./watchlist"
 
 /** The protocol revisions the server speaks, newest first: a client's supported one is echoed, else the newest. */
@@ -205,7 +208,7 @@ function inboxText(box: Inbox): string {
 /** One message (message_show): its state, the message and, once answered or declined, the answer, in envelopes. */
 function messageText({ message, answer }: Asked): string {
   // (CON-10) A message dropped for a recipient that ended for good says so.
-  const lines = [NOT_FROM_USER, `${message.kind} ${message.id}: ${message.state}${message.delivery === "dropped" ? ` · ${deliveryText("dropped")}` : ""}`, envelope(message)]
+  const lines = [NOT_FROM_USER, `${message.kind} ${message.id}: ${message.state}${message.delivery === "dropped" || message.delivery === "expired" ? ` · ${deliveryText(message.delivery)}` : ""}`, envelope(message)]
   if (answer) lines.push(`${message.state} by ${answer.id}:`, envelope(answer))
   return lines.join("\n")
 }
@@ -732,6 +735,7 @@ const TOOLS: readonly Tool[] = [
   eventsTool,
   ...webhookTools,
   ...profileTools,
+  ...profileLifecycleTools,
   ...workspaceTools,
   ...artifactTools,
   ...artifactJobTools,
@@ -1139,7 +1143,7 @@ export function createMcpServer(options: McpServerOptions): McpServer {
       return controller.signal.aborted ? undefined : ok(id, toolResult(clean(text, token), false))
     } catch (cause) {
       if (controller.signal.aborted) return undefined // cancelled: no answer (MCP cancellation)
-      const text = cause instanceof ArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
+      const text = cause instanceof ArgError || cause instanceof ProfileArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
       return ok(id, toolResult(clean(text, token), true))
     } finally {
       if (inFlight.get(key(id)) === controller) inFlight.delete(key(id))

package/packages/cli/src/messaging.ts

@@ -1,6 +1,7 @@
 // The messaging verbs' helpers (design §3): text arguments (or "-" for stdin) and the short text of what the hub
 // answers to msg, ask, reply, decline, inbox and mute. The shapes are packages/sdk's types (message-routes.ts).
 import type { AgentMessage, Asked, Inbox, MessageDelivery, Party, Replied, Sent } from "../../sdk/src/index.ts"
+import { wakeSkipNote } from "../../sdk/src/wake.ts"
 import { UsageError } from "./args"
 import { oneLine } from "./format"
 
@@ -30,6 +31,7 @@ const DELIVERY: Record<MessageDelivery, string> = {
   // Offline recipients, and a --no-wake message to a busy OpenCode session (RF-05); the hub's answer does not say which.
   pending: "pending (offline or busy; delivered when it reconnects or its turn ends, for 24 h)",
   dropped: "not delivered (its recipient session ended)",
+  expired: "not delivered (its recipient stayed offline or busy for 24 h)",
 }
 
 export const deliveryText = (delivery: MessageDelivery | undefined): string => (delivery ? (DELIVERY[delivery] ?? delivery) : "stored (in its inbox)")
@@ -40,8 +42,8 @@ function toText(message: AgentMessage): string {
   return message.to === recipient || message.to === (message.recipient as { sessionID?: string }).sessionID ? recipient : `${message.to} → ${recipient}`
 }
 
-/** `msg_… to @web-work: delivered (started a turn)` */
-export const sentText = ({ message, delivery }: Sent): string => `${message.kind} ${message.id} to ${toText(message)}: ${deliveryText(delivery)}`
+/** `msg_… to @web-work: delivered (started a turn)`; `…: queued (read at its next turn) — wake skipped: …` */
+export const sentText = (sent: Sent): string => `${sent.message.kind} ${sent.message.id} to ${toText(sent.message)}: ${deliveryText(sent.delivery)}${wakeSkipNote(sent)}`
 
 /** How long an ask stays open when --expires is not given (the hub's default). */
 export const ASK_EXPIRES_DEFAULT_S = 24 * 60 * 60

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 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). */
+export class ProfileArgError extends Error {}
+const ArgError = ProfileArgError
+
+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",