@huynle/hub 0.8.0 → 0.8.2

package/packages/cli/package.json

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

@@ -7,6 +7,7 @@
 // (+ artifacts:read) for an app token. Content never travels in requests or job listings, only in the context.
 import type { ArtifactJob, ArtifactJobContext, ArtifactJobKind, ArtifactJobRequest } from "../../sdk/src/artifact-jobs.ts"
 import type { Artifacts } from "../../sdk/src/artifacts.ts"
+import { ToolArgError } from "./tool-args"
 
 /** UTF-8 bytes of the inline proposal text one tool call may carry. */
 export const MCP_JOB_TEXT_BYTES = 256 * 1024
@@ -33,27 +34,27 @@ const KINDS: readonly ArtifactJobKind[] = ["ask", "propose-edit", "run-action"]
 
 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 integer = (args: Args, key: string): number => {
   const value = args[key]
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`"${key}" is required (a whole number)`)
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ToolArgError(`"${key}" is required (a whole number)`)
   return value
 }
 
 function handlerOf(args: Args): ArtifactJobRequest["handler"] {
   const session = optional(args, "session")
   const machine = optional(args, "machine")
-  if (session && machine) throw new Error('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both')
+  if (session && machine) throw new ToolArgError('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both')
   if (session) return { session }
-  if (!machine) throw new Error('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")')
+  if (!machine) throw new ToolArgError('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")')
   const repo = need(args, "repo")
   const harness = optional(args, "harness")
   const model = optional(args, "model")
@@ -114,7 +115,7 @@ export const artifactJobTools: readonly ArtifactJobTool[] = [
     readOnly: false,
     run: async (hub, args, signal) => {
       const kind = optional(args, "kind") as ArtifactJobKind | undefined
-      if (kind && !KINDS.includes(kind)) throw new Error(`"kind" must be one of ${KINDS.join(", ")}`)
+      if (kind && !KINDS.includes(kind)) throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`)
       const action = optional(args, "action")
       const apply = optional(args, "apply") as "manual" | "auto" | undefined
       const key = optional(args, "key")
@@ -181,10 +182,10 @@ export const artifactJobTools: readonly ArtifactJobTool[] = [
       const error = optional(args, "error")
       const answer = optional(args, "answer")
       const text = args.text
-      if (text !== undefined && typeof text !== "string") throw new Error('"text" must be a string')
-      if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES) throw new Error(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`)
+      if (text !== undefined && typeof text !== "string") throw new ToolArgError('"text" must be a string')
+      if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES) throw new ToolArgError(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`)
       const keep = args.keep
-      if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string"))) throw new Error('"keep" must be a list of paths')
+      if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string"))) throw new ToolArgError('"keep" must be a list of paths')
       const path = optional(args, "path")
       const entry = optional(args, "entry")
       const result = error

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

@@ -5,6 +5,7 @@
 // tool ever reads local files). Needs scope artifacts:read / artifacts:write for an app token; sessions create and
 // read workspace-shared artifacts only (revising stays with the user in v1).
 import type { Artifact, ArtifactKind, ArtifactRevision, Artifacts, BlobRef } from "../../sdk/src/artifacts.ts"
+import { ToolArgError } from "./tool-args"
 
 /** UTF-8 bytes of inline text one tool call may carry (bigger content: stage it, then pass `blobs`). */
 export const MCP_INLINE_TEXT_BYTES = 256 * 1024
@@ -45,24 +46,24 @@ const FILE_ARGS = {
 
 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
 }
 
 /** The files of a publish/revise: inline text and/or blob references (one of them required). */
 function files(args: Args, kind: ArtifactKind | undefined): { blobs?: BlobRef[]; upload?: { mediaType: string; data: string; path?: string }[]; entry?: string } {
   const text = args.text
-  if (text !== undefined && typeof text !== "string") throw new Error('"text" must be a string')
+  if (text !== undefined && typeof text !== "string") throw new ToolArgError('"text" must be a string')
   const blobs = args.blobs
-  if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null))) throw new Error('"blobs" must be a list of blob references')
-  if (text === undefined && (blobs === undefined || blobs.length === 0)) throw new Error('give text or blobs (stage bigger content first and pass its reference)')
-  if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES) throw new Error(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`)
+  if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null))) throw new ToolArgError('"blobs" must be a list of blob references')
+  if (text === undefined && (blobs === undefined || blobs.length === 0)) throw new ToolArgError('give text or blobs (stage bigger content first and pass its reference)')
+  if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES) throw new ToolArgError(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`)
   const path = optional(args, "path")
   const entry = optional(args, "entry")
   const mediaType = optional(args, "mediaType") ?? (kind && DEFAULT_MEDIA[kind]) ?? "text/plain"
@@ -126,7 +127,7 @@ export const artifactTools: readonly ArtifactTool[] = [
     run: async (hub, args, signal) => {
       const title = need(args, "title")
       const kind = need(args, "kind") as ArtifactKind
-      if (!KINDS.includes(kind)) throw new Error(`"kind" must be one of ${KINDS.join(", ")}`)
+      if (!KINDS.includes(kind)) throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`)
       const body = files(args, kind)
       const description = optional(args, "description")
       const visibility = optional(args, "visibility") as "private" | "workspace" | undefined

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,8 @@ import { artifactTools } from "./artifacts-mcp"
 import { artifactJobTools } from "./artifact-jobs-mcp"
 import { teamIntakeTools } from "./team-intake-mcp"
 import { teamTools } from "./teams-mcp"
+import { profileLifecycleTools } from "./profiles-mcp"
+import { ToolArgError } from "./tool-args"
 import { watchlistTools } from "./watchlist"
 
 /** The protocol revisions the server speaks, newest first: a client's supported one is echoed, else the newest. */
@@ -45,7 +49,7 @@ type Id = string | number | null
 type Args = Record<string, unknown>
 
 /** A bad tool argument (an isError result, not a protocol error). */
-class ArgError extends Error {}
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
@@ -205,7 +209,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 +736,7 @@ const TOOLS: readonly Tool[] = [
   eventsTool,
   ...webhookTools,
   ...profileTools,
+  ...profileLifecycleTools,
   ...workspaceTools,
   ...artifactTools,
   ...artifactJobTools,
@@ -1139,7 +1144,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 ToolArgError ? `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