@pellux/goodvibes-agent 1.8.0 → 1.8.2

package/src/cli/connected-host-metrics.ts

@@ -0,0 +1,165 @@
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
+
+/**
+ * Reads the connected daemon host's process-wide runtime metrics snapshot via
+ * the operator gateway's `runtime.metrics.get` verb (REST binding
+ * GET /api/runtime/metrics, scope read:telemetry) so `goodvibes-agent status`
+ * can show live host counters/gauges alongside the rest of the connected-host
+ * posture.
+ *
+ * Honesty is the whole point of the classification below: the metrics route
+ * requires the read:telemetry scope, and a token without it is answered 403 by
+ * the gateway. That case is reported as `scope_missing` and rendered as a plain
+ * "not permitted" line — never as a screen of zeros that would misrepresent an
+ * unauthorized token as a healthy-but-idle host. Missing token, an unreachable
+ * host, and an incompatible/absent route are each surfaced as their own honest
+ * state too.
+ */
+
+export type CliConnectedHostMetricsStatus =
+  | 'ok'
+  | 'auth_required'
+  | 'scope_missing'
+  | 'route_unavailable'
+  | 'unavailable'
+  | 'error';
+
+/** The compact, already-narrowed set of host metrics this surface renders. */
+export interface CliConnectedHostMetrics {
+  readonly httpRequestsTotal: number;
+  readonly llmRequestsTotal: number;
+  readonly authSuccessTotal: number;
+  readonly authFailureTotal: number;
+  readonly transportRetriesTotal: number;
+  readonly sessionsActive: number;
+  readonly sseSubscribers: number;
+  readonly telemetryBufferFill: number;
+}
+
+export interface CliConnectedHostMetricsSnapshot {
+  readonly route: '/api/runtime/metrics';
+  readonly methodId: 'runtime.metrics.get';
+  readonly requiredScope: 'read:telemetry';
+  readonly status: CliConnectedHostMetricsStatus;
+  readonly statusCode: number | null;
+  readonly metrics: CliConnectedHostMetrics | null;
+  readonly error: string | null;
+}
+
+export interface CliConnectedHostMetricsInspectionOptions {
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly homeDirectory: string;
+  readonly timeoutMs?: number;
+}
+
+// Same base-url resolution the connected-host status probe uses
+// (cli/external-runtime.ts): controlPlane.host/port, defaulting to the local
+// daemon. Kept in step with that module so both probes target one host.
+function resolveBaseUrl(configManager: Pick<ConfigManager, 'get'>): string {
+  const host = String(configManager.get('controlPlane.host') ?? '127.0.0.1');
+  const port = Number(configManager.get('controlPlane.port') ?? 3421);
+  return `http://${host}:${Number.isFinite(port) ? port : 3421}`;
+}
+
+function readNumber(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/** Sum a counter bucket (label -> count), tolerating a missing/!object bucket. */
+function sumBucket(value: unknown): number {
+  if (!value || typeof value !== 'object') return 0;
+  let total = 0;
+  for (const entry of Object.values(value as Record<string, unknown>)) total += readNumber(entry);
+  return total;
+}
+
+function narrowMetrics(body: unknown): CliConnectedHostMetrics | null {
+  if (!body || typeof body !== 'object') return null;
+  const root = body as Record<string, unknown>;
+  const counters = (root.counters ?? {}) as Record<string, unknown>;
+  const gauges = (root.gauges ?? {}) as Record<string, unknown>;
+  const http = (counters.http ?? {}) as Record<string, unknown>;
+  const llm = (counters.llm ?? {}) as Record<string, unknown>;
+  const auth = (counters.auth ?? {}) as Record<string, unknown>;
+  const transport = (counters.transport ?? {}) as Record<string, unknown>;
+  const sessions = (gauges.sessions ?? {}) as Record<string, unknown>;
+  const sse = (gauges.sse ?? {}) as Record<string, unknown>;
+  const telemetry = (gauges.telemetry ?? {}) as Record<string, unknown>;
+  const httpRequests = (http.requests ?? {}) as Record<string, unknown>;
+  const llmRequests = (llm.requests ?? {}) as Record<string, unknown>;
+  const authSuccess = (auth.success ?? {}) as Record<string, unknown>;
+  const authFailure = (auth.failure ?? {}) as Record<string, unknown>;
+  const telemetryBuffer = (telemetry.buffer ?? {}) as Record<string, unknown>;
+  return {
+    httpRequestsTotal: sumBucket(httpRequests.total),
+    llmRequestsTotal: sumBucket(llmRequests.total),
+    authSuccessTotal: readNumber(authSuccess.total),
+    authFailureTotal: readNumber(authFailure.total),
+    transportRetriesTotal: readNumber(transport.retries_total),
+    sessionsActive: readNumber(sessions.active),
+    sseSubscribers: readNumber(sse.subscribers),
+    telemetryBufferFill: readNumber(telemetryBuffer.fill),
+  };
+}
+
+export async function inspectConnectedHostMetrics(
+  options: CliConnectedHostMetricsInspectionOptions,
+): Promise<CliConnectedHostMetricsSnapshot> {
+  const route = '/api/runtime/metrics' as const;
+  const base = {
+    route,
+    methodId: 'runtime.metrics.get' as const,
+    requiredScope: 'read:telemetry' as const,
+  };
+  const baseUrl = resolveBaseUrl(options.configManager);
+  const token = readConnectedHostOperatorToken(options.homeDirectory);
+  if (!token.token) {
+    return { ...base, status: 'auth_required', statusCode: null, metrics: null, error: `No connected-host operator token found at ${token.path}` };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 1500);
+  try {
+    const response = await fetch(`${baseUrl}${route}`, {
+      headers: { authorization: `Bearer ${token.token}` },
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    let body: unknown = text;
+    if (text.trim().length > 0) {
+      try {
+        body = JSON.parse(text) as unknown;
+      } catch {
+        body = text;
+      }
+    }
+
+    if (response.ok) {
+      const metrics = narrowMetrics(body);
+      return metrics
+        ? { ...base, status: 'ok', statusCode: response.status, metrics, error: null }
+        : { ...base, status: 'error', statusCode: response.status, metrics: null, error: 'Connected host returned a runtime metrics body Agent could not read.' };
+    }
+    // 403 is the token-lacks-read:telemetry case: report it plainly rather than
+    // rendering zeros. 401 is unauthenticated; 404 means the route/verb is not
+    // present on this host (older or incompatible daemon).
+    const status: CliConnectedHostMetricsStatus =
+      response.status === 403 ? 'scope_missing'
+        : response.status === 401 ? 'auth_required'
+          : response.status === 404 ? 'route_unavailable'
+            : 'error';
+    return {
+      ...base,
+      status,
+      statusCode: response.status,
+      metrics: null,
+      error: typeof body === 'string' && body.trim() ? body : `HTTP ${response.status}`,
+    };
+  } catch (error) {
+    return { ...base, status: 'unavailable', statusCode: null, metrics: null, error: summarizeError(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/cli/entrypoint.ts

@@ -5,7 +5,7 @@ import { formatProviderModel, getModelIdFromProviderModel, getProviderIdFromMode
 import { readOnboardingCheckMarkers } from '../runtime/onboarding/index.ts';
 import { GlobalNetworkTransportInstaller } from '@/runtime/index.ts';
 import { createShellPathService } from '@/runtime/index.ts';
-import { configureActivityLogger } from '@pellux/goodvibes-sdk/platform/utils';
+import { configureActivityLogger, logger } from '@pellux/goodvibes-sdk/platform/utils';
 import {
   applyRuntimeCommandEndpointFlagOverrides,
   applyRuntimeConfigOverrides,
@@ -24,7 +24,10 @@ import {
 } from './index.ts';
 import { buildCliServicePosture } from './service-posture.ts';
 import { inspectCliExternalRuntime } from './external-runtime.ts';
+import { inspectConnectedHostMetrics } from './connected-host-metrics.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { readCheckpointRegistrationSetting } from '../config/checkpoint-settings.ts';
+import { migrateLegacyWorkspaceRegistryIfNeeded, resolveWorkspaceRegistrationSync } from '../config/workspace-registration.ts';
 import { resolveAgentRuntimeProfileHome, resolveSelectedAgentRuntimeProfileHome } from '../agent/runtime-profile.ts';
 
 type ShellEntrypointOwnership = {
@@ -186,14 +189,34 @@ export async function prepareShellCliRuntime(
       configManager,
       homeDirectory: bootstrapHomeDirectory,
     });
+    // Only probe host metrics when the host is actually reachable — otherwise
+    // the unreachability is already reported in the connected-host block above,
+    // and skipping the call avoids a second connect-timeout wait. When reachable,
+    // the probe classifies token/scope/route state honestly (including the
+    // read:telemetry scope-missing case) rather than rendering zeros.
+    const connectedHostMetrics = externalRuntime.reachable
+      ? await inspectConnectedHostMetrics({
+        configManager,
+        homeDirectory: bootstrapHomeDirectory,
+      })
+      : undefined;
     const effectiveOperatorTokenPath = externalRuntime.operatorToken.present
       ? externalRuntime.operatorToken.path
       : operatorTokenPath;
+    const registrationMigration = migrateLegacyWorkspaceRegistryIfNeeded(shellPaths);
+    if (registrationMigration) {
+      logger.info('Migrated the local workspace registry into the shared registration store', { ...registrationMigration });
+    }
+    const checkpoints = {
+      workspaceRegistered: resolveWorkspaceRegistrationSync(shellPaths, bootstrapWorkingDir).status === 'covered',
+      unregisteredWorkspaceMode: readCheckpointRegistrationSetting(configManager),
+    };
     const statusOptions = {
       configManager,
       workingDirectory: bootstrapWorkingDir,
       homeDirectory: bootstrapHomeDirectory,
       onboardingMarkers,
+      checkpoints,
       auth: {
         userStorePath,
         userStorePresent: existsSync(userStorePath),
@@ -204,6 +227,7 @@ export async function prepareShellCliRuntime(
       },
       service,
       externalRuntime,
+      connectedHostMetrics,
       doctor: cli.command === 'doctor',
       outputFormat: cli.flags.outputFormat,
     };

package/src/cli/fleet-command.ts

@@ -0,0 +1,178 @@
+import type {
+  AttemptCandidate,
+  AttemptJudgment,
+  AttemptPickResult,
+  HeldMergeGroup,
+} from '@pellux/goodvibes-sdk/platform/orchestration';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import {
+  operatorFlagValue,
+  parseOperatorCommandArgs,
+} from './operator-command-args.ts';
+import { withRuntimeServices } from './management.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+
+/**
+ * `goodvibes-agent fleet` — the best-of-N attempts admin surface (SDK 1.6.1
+ * orchestration engine held-merge groups). Unlike ci/principals/channel-
+ * profiles (which reach a REMOTE connected host over HTTP), fleet.attempts.*
+ * is ws-only on the wire (no HTTP binding — see method-catalog-fleet.ts) and
+ * reads THIS agent's own orchestration engine, which persists workstream
+ * state to disk (.goodvibes/orchestration/<workstreamId>.json). So this
+ * command goes through withRuntimeServices (the same in-process
+ * RuntimeServices construction `tasks`/`sessions` already use — see
+ * management.ts), not the operator-gateway-call HTTP path ci-command.ts
+ * uses: calling sdk.operator.invoke on a method with no `http` binding always
+ * throws (methodHttpRoute in @pellux/goodvibes-operator-sdk), so the HTTP
+ * path can never reach these three verbs regardless of connection health.
+ * services.orchestrationEngine is the exact same FleetAttemptsController
+ * instance the fleet.attempts.* gateway verb handlers are wired to in
+ * runtime/services.ts, so this CLI and the gateway verbs read/write
+ * identical state.
+ */
+
+const FLEET_ATTEMPTS_PICK_USAGE = 'Usage: goodvibes-agent fleet attempts pick <groupId> <winnerItemId> --yes';
+const FLEET_ATTEMPTS_JUDGE_USAGE = 'Usage: goodvibes-agent fleet attempts judge <groupId>';
+const FLEET_USAGE = 'Usage: goodvibes-agent fleet attempts [list [--workstream <workstreamId>]|pick <groupId> <winnerItemId> --yes|judge <groupId>]';
+
+function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+function usageFailure(runtime: CliCommandRuntime, error: string): CliCommandOutput {
+  return {
+    output: jsonOrText(runtime, { ok: false, kind: 'invalid_fleet_command', error }, error),
+    exitCode: 2,
+  };
+}
+
+function errorFailure(runtime: CliCommandRuntime, error: unknown): CliCommandOutput {
+  const message = summarizeError(error);
+  return {
+    output: jsonOrText(runtime, { ok: false, kind: 'fleet_attempts_error', error: message }, message),
+    exitCode: 1,
+  };
+}
+
+/** The model proposal is clearly labeled at every point it renders — never presented as a decision. */
+function renderJudgment(judgment: AttemptJudgment | null): readonly string[] {
+  if (!judgment) return ['    judge proposal: none yet'];
+  const winner = judgment.proposedWinnerItemId ?? '(judge declined to choose)';
+  const lines = [
+    `    MODEL PROPOSAL (scored by ${judgment.model ?? 'unknown model'}, not a decision — confirm with fleet attempts pick)`,
+    `      proposed winner ${winner}`,
+  ];
+  for (const reason of judgment.reasons) lines.push(`      reason: ${reason}`);
+  return lines;
+}
+
+function renderCandidate(candidate: AttemptCandidate): readonly string[] {
+  const lines = [
+    `    ${candidate.itemId}  attempt #${candidate.attemptIndex}  ${candidate.state}  ${candidate.title}`,
+  ];
+  if (candidate.state === 'failed' && candidate.failureReason) {
+    lines.push(`      failure: ${candidate.failureReason}`);
+  }
+  if (candidate.diff) {
+    lines.push(`      diff: ${candidate.diff.files.length} file(s) — ${candidate.diff.stat}`);
+  }
+  const usage = candidate.usage;
+  const cost = usage.costState === 'priced' && usage.costUsd !== null ? `$${usage.costUsd.toFixed(4)}` : usage.costState;
+  lines.push(`      usage: ${usage.turnCount} turn(s), ${usage.toolCallCount} tool call(s), cost ${cost}`);
+  return lines;
+}
+
+function renderGroup(group: HeldMergeGroup): string {
+  return [
+    `  ${group.groupId}  workstream ${group.workstreamId}  ${group.sourceTitle}`,
+    `    ready ${group.ready ? 'yes' : 'no'}  autoAccept ${group.autoAccept ? 'yes' : 'no'}  candidates ${group.candidates.length}`,
+    ...group.candidates.flatMap(renderCandidate),
+    ...renderJudgment(group.judgment),
+  ].join('\n');
+}
+
+function renderGroupList(groups: readonly HeldMergeGroup[]): string {
+  if (groups.length === 0) {
+    return [
+      'Best-of-N held-merge groups',
+      '  No groups are currently held for a winner pick.',
+    ].join('\n');
+  }
+  return [`Best-of-N held-merge groups (${groups.length})`, ...groups.map(renderGroup)].join('\n\n');
+}
+
+async function handleFleetAttemptsList(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args, ['workstream']);
+  const workstreamId = operatorFlagValue(parsed, 'workstream');
+  try {
+    const groups = await withRuntimeServices(runtime, (services) => services.orchestrationEngine.listHeldMergeGroups(workstreamId));
+    return { output: jsonOrText(runtime, { ok: true, groups }, renderGroupList(groups)), exitCode: 0 };
+  } catch (error) {
+    return errorFailure(runtime, error);
+  }
+}
+
+async function handleFleetAttemptsPick(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args);
+  const groupId = parsed.positionals[0];
+  const winnerItemId = parsed.positionals[1];
+  if (!groupId || !winnerItemId) return usageFailure(runtime, FLEET_ATTEMPTS_PICK_USAGE);
+  if (!parsed.yes) {
+    return { output: `Refusing to pick a winner for group ${groupId} without --yes. Losing siblings' worktrees are cleaned on pick.`, exitCode: 2 };
+  }
+  try {
+    const result: AttemptPickResult = await withRuntimeServices(runtime, (services) => services.orchestrationEngine.pickAttemptWinner(groupId, winnerItemId));
+    const text = [
+      `Picked winner ${result.winnerItemId} for group ${result.groupId}`,
+      `  losers cleaned: ${result.loserItemIds.length === 0 ? 'none' : result.loserItemIds.join(', ')}`,
+      `  auto-picked ${result.auto ? 'yes (judge auto-accept)' : 'no (explicit operator pick)'}`,
+    ].join('\n');
+    return { output: jsonOrText(runtime, { ok: true, ...result }, text), exitCode: 0 };
+  } catch (error) {
+    return errorFailure(runtime, error);
+  }
+}
+
+async function handleFleetAttemptsJudge(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args);
+  const groupId = parsed.positionals[0];
+  if (!groupId) return usageFailure(runtime, FLEET_ATTEMPTS_JUDGE_USAGE);
+  try {
+    const judgment: AttemptJudgment = await withRuntimeServices(runtime, (services) => services.orchestrationEngine.proposeAttemptWinner(groupId));
+    const text = [
+      `Judge proposal for group ${groupId}`,
+      ...renderJudgment(judgment),
+      '',
+      'This is a model judgment, not a decision. Confirm with:',
+      `  goodvibes-agent fleet attempts pick ${groupId} <winnerItemId> --yes`,
+    ].join('\n');
+    return { output: jsonOrText(runtime, { ok: true, judgment }, text), exitCode: 0 };
+  } catch (error) {
+    return errorFailure(runtime, error);
+  }
+}
+
+async function handleFleetAttemptsCommand(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const [sub = 'list', ...rest] = args;
+  switch (sub.toLowerCase()) {
+    case 'list':
+      return handleFleetAttemptsList(runtime, rest);
+    case 'pick':
+      return handleFleetAttemptsPick(runtime, rest);
+    case 'judge':
+      return handleFleetAttemptsJudge(runtime, rest);
+    default:
+      return usageFailure(runtime, FLEET_USAGE);
+  }
+}
+
+export async function handleFleetCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const [sub, ...rest] = runtime.cli.commandArgs;
+  switch ((sub ?? '').toLowerCase()) {
+    case 'attempts':
+      return handleFleetAttemptsCommand(runtime, rest);
+    default:
+      return usageFailure(runtime, FLEET_USAGE);
+  }
+}

package/src/cli/help.ts

@@ -56,6 +56,12 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  skills                     Manage local Agent skills and skill bundles',
     '  memory                     Manage Agent-owned durable memory records',
     '  routines                   Inspect local routines and explicitly promote one to a connected schedule',
+    '  ci                         Check connected-host CI status and manage standing CI watches',
+    '  principals                 Manage the connected-host cross-channel principal identity registry',
+    '  channel-profiles           Manage per-channel model/provider/permission-mode defaults',
+    '  workspaces                 Manage which workspaces get automatic checkpoints',
+    '  relay                      Report the connected host\'s outbound relay configuration (status|pair)',
+    '  fleet                      Review and resolve this Agent\'s best-of-N attempt groups',
     '  auth                       Inspect Agent auth posture and connection token state',
     '  compat                     Inspect connected-host compatibility and Agent Knowledge route readiness',
     '  knowledge                  Use isolated Agent Knowledge routes',
@@ -67,6 +73,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  pair|qrcode                Print companion pairing payload and QR code',
     '  bundle export|inspect|import',
     '                             Move setup/profile/trust/support bundles',
+    '  import openclaw [path]     Migrate an OpenClaw workspace (dry-run default, --apply to write)',
     '  completion <shell>         Generate shell completion script',
     '  help [command]             Print this help or command-specific help',
     '  version                    Print version',
@@ -112,6 +119,11 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     `  ${binary} memory add fact "Prefers concise morning briefings" --scope project --tags preference`,
     `  ${binary} memory search "morning briefings"`,
     `  ${binary} routines promote daily-operations-sweep --cron "0 9 * * *" --timezone America/Chicago --yes`,
+    `  ${binary} ci status my-org/my-repo --ref main`,
+    `  ${binary} ci watches create my-org/my-repo --ref main --delivery-channel slack:C123 --yes`,
+    `  ${binary} principals resolve --channel slack --value U123`,
+    `  ${binary} channel-profiles set slack --model openai:gpt-5.4 --permission-mode plan --yes`,
+    `  ${binary} fleet attempts list`,
     `  ${binary} compat`,
     `  ${binary} knowledge status`,
     `  ${binary} knowledge ask "What is GoodVibes Agent?"`,
@@ -290,6 +302,95 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     summary: 'List, inspect, select, pin, and review model choices.',
     examples: ['models current', 'models openai', 'models use openai:gpt-5.4'],
   },
+  ci: {
+    usage: [
+      'ci status <repo> [--ref <ref>] [--pr <number>]',
+      'ci watches list',
+      'ci watches create <repo> --delivery-channel <channel> [--ref <ref>] [--pr <number>] [--trigger-fix-session] --yes',
+      'ci watches delete <watchId> --yes',
+      'ci watches run <watchId>',
+    ],
+    summary: 'Check per-job CI status on the connected host and manage standing CI watches. Status is always rendered per job (name, status, conclusion), never collapsed to a single rollup.',
+    examples: [
+      'ci status my-org/my-repo --ref main',
+      'ci status my-org/my-repo --pr 42',
+      'ci watches list',
+      'ci watches create my-org/my-repo --ref main --delivery-channel slack:C123 --yes',
+      'ci watches run watch-123',
+      'ci watches delete watch-123 --yes',
+    ],
+  },
+  principals: {
+    usage: [
+      'principals list',
+      'principals get <id>',
+      'principals create --name <name> --kind <user|bot|service|token> [--identity channel:value,channel:value] --yes',
+      'principals update <id> [--name <name>] [--kind <kind>] [--identity channel:value,channel:value] --yes',
+      'principals delete <id> --yes',
+      'principals resolve --channel <channel> --value <value>',
+    ],
+    summary: 'Manage the connected-host cross-channel principal identity registry, mapping channel-specific sender identities (a Slack user id, an email address, a phone number) onto one named principal. resolve reports known: false rather than asserting a match when no identity is mapped.',
+    examples: [
+      'principals list',
+      'principals create --name "Mike Davis" --kind user --identity slack:U123,email:mike@example.com --yes',
+      'principals resolve --channel slack --value U123',
+      'principals delete principal-1 --yes',
+    ],
+  },
+  'channel-profiles': {
+    usage: [
+      'channel-profiles list',
+      'channel-profiles get <surfaceKind> [--channel-id <id>]',
+      'channel-profiles set <surfaceKind> [--channel-id <id>] [--model <model>] [--provider <provider>] [--permission-mode <plan|normal|accept-edits|auto>] --yes',
+      'channel-profiles delete <surfaceKind> [--channel-id <id>] --yes',
+    ],
+    summary: 'Manage per-channel default model, provider, and permission-mode bindings applied to sessions that channel originates.',
+    examples: [
+      'channel-profiles list',
+      'channel-profiles set slack --model openai:gpt-5.4 --permission-mode plan --yes',
+      'channel-profiles get slack',
+      'channel-profiles delete slack --yes',
+    ],
+  },
+  workspaces: {
+    usage: [
+      'workspaces list',
+      'workspaces register [path] [--label <label>] --yes',
+      'workspaces unregister [path] --yes',
+    ],
+    summary: 'Manage the registered-workspace list that gates automatic (turn-end/lifecycle) checkpoints. A workspace not in this list gets no automatic checkpoints; path defaults to the current working directory.',
+    examples: [
+      'workspaces list',
+      'workspaces register --yes',
+      'workspaces register /home/mike/Projects/goodvibes-agent --label agent --yes',
+      'workspaces unregister --yes',
+    ],
+  },
+  relay: {
+    usage: [
+      'relay status',
+      'relay pair',
+    ],
+    summary: 'Report the connected GoodVibes host\'s imported relay.* configuration and the relay-connect feature flag. Agent hosts no daemon itself, so this is not a live check, and relay pair honestly refuses — pairing payloads are minted by whichever daemon holds the relay identity key.',
+    examples: [
+      'relay status',
+      'relay pair',
+    ],
+  },
+  fleet: {
+    usage: [
+      'fleet attempts list [--workstream <workstreamId>]',
+      'fleet attempts pick <groupId> <winnerItemId> --yes',
+      'fleet attempts judge <groupId>',
+    ],
+    summary: 'Review and resolve this Agent\'s own best-of-N attempt groups (orchestration engine state, disk-persisted, not a connected-host call): siblings that ran in isolated worktrees and are held for a winner pick instead of auto-merging. judge runs the optional judge model and PROPOSES a winner (clearly labeled as a model proposal, never an auto-decision); pick is the confirm-gated action that actually merges the winner and cleans losing worktrees.',
+    examples: [
+      'fleet attempts list',
+      'fleet attempts list --workstream workstream-1',
+      'fleet attempts judge group-1',
+      'fleet attempts pick group-1 item-2 --yes',
+    ],
+  },
   auth: {
     usage: ['auth', 'auth status', 'auth review', 'auth users', 'auth sessions'],
     summary: 'Inspect Agent auth posture and connection token state. Runtime user/session administration stays outside Agent.',
@@ -381,6 +482,15 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     summary: 'Print companion pairing connection details and a QR code.',
     examples: ['pair', 'qrcode'],
   },
+  import: {
+    usage: ['import openclaw [path] [--apply]'],
+    summary: 'Migrate an OpenClaw workspace into the Agent registries. Dry-run is the default; it prints the personas, memory records, skills, and permission allowlist categories that would be created, plus any skipped files with reasons. Re-run with --apply to write through the persona registry, the canonical memory store, the skill registry, and the permission settings. Reads ~/.openclaw by default, or a supplied path.',
+    examples: [
+      'import openclaw',
+      'import openclaw ~/.openclaw',
+      'import openclaw ~/.openclaw --apply',
+    ],
+  },
   completion: {
     usage: ['completion <bash|zsh|fish>'],
     summary: 'Generate shell completion scripts.',
@@ -401,6 +511,10 @@ const HELP_ALIASES: Record<string, string> = {
   'agent-skills': 'skills',
   memories: 'memory',
   routine: 'routines',
+  principal: 'principals',
+  'channel-profile': 'channel-profiles',
+  workspace: 'workspaces',
+  fleets: 'fleet',
   know: 'knowledge',
   kb: 'knowledge',
   find: 'search',
@@ -412,6 +526,7 @@ const HELP_ALIASES: Record<string, string> = {
   bundles: 'bundle',
   qrcode: 'pair',
   qr: 'pair',
+  migrate: 'import',
   completions: 'completion',
 };