@pellux/goodvibes-agent 1.8.1 → 1.8.2

package/src/agent/principal-attribution.ts

@@ -0,0 +1,97 @@
+/**
+ * principal-attribution.ts
+ *
+ * Shared "honest inbound attribution" helper. Anywhere the Agent displays who a
+ * session or message came from, it should show the RESOLVED principal when the
+ * sender's channel identity maps to one, and plainly say "unknown principal"
+ * when it does not — never a blank field, never a guess.
+ *
+ * Resolution goes through the connected host's `principals.resolve` operator
+ * method: POST /api/principals/resolve with `{ channel, value }`, returning
+ * `{ principal, known }`. An unmapped identity resolves to `known: false` —
+ * the registry never guesses, and neither does this helper.
+ *
+ * Every failure mode (empty channel identity, no connected-host token, a
+ * failed/unreachable resolve call, or an explicit `known: false`) collapses to
+ * the same human-facing label, `UNKNOWN_PRINCIPAL_LABEL`, so the display never
+ * over-claims certainty about which failure occurred. Callers that want the
+ * underlying detail can read the optional `error` field separately.
+ */
+
+import { createBrowserGoodVibesSdk } from '@pellux/goodvibes-sdk/browser';
+import type { OperatorMethodInput, OperatorMethodOutput } from '@pellux/goodvibes-sdk/contracts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+export const UNKNOWN_PRINCIPAL_LABEL = 'unknown principal';
+
+export interface PrincipalAttributionConnection {
+  readonly baseUrl: string;
+  readonly token: string | null;
+}
+
+export interface ResolvedPrincipalSummary {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: string;
+}
+
+export interface ResolvedPrincipalAttribution {
+  readonly known: boolean;
+  readonly label: string;
+  readonly principal: ResolvedPrincipalSummary | null;
+  /** Diagnostic detail only — never surfaced in `label` itself. */
+  readonly error?: string;
+}
+
+type PrincipalsResolveInput = OperatorMethodInput<'principals.resolve'>;
+type PrincipalsResolveOutput = OperatorMethodOutput<'principals.resolve'>;
+
+const UNKNOWN_ATTRIBUTION: ResolvedPrincipalAttribution = {
+  known: false,
+  label: UNKNOWN_PRINCIPAL_LABEL,
+  principal: null,
+};
+
+export function formatPrincipalLabel(principal: ResolvedPrincipalSummary): string {
+  return `${principal.name} (${principal.id})`;
+}
+
+/**
+ * Resolve a channel identity ({channel, value}) to its named principal for
+ * honest inbound-attribution display.
+ *
+ * Never fabricates a name. Returns the shared "unknown principal" label
+ * (never a blank string) when: the identity is empty, no connected-host
+ * operator token is available, or the resolve call fails or returns
+ * `known: false`.
+ */
+export async function resolveChannelPrincipalAttribution(
+  connection: PrincipalAttributionConnection,
+  channel: string,
+  value: string,
+): Promise<ResolvedPrincipalAttribution> {
+  if (!channel.trim() || !value.trim()) return UNKNOWN_ATTRIBUTION;
+  if (!connection.token) {
+    return { ...UNKNOWN_ATTRIBUTION, error: 'No connected-host operator token available for principal resolution.' };
+  }
+  try {
+    const sdk = createBrowserGoodVibesSdk({
+      baseUrl: connection.baseUrl,
+      authToken: connection.token,
+      // A single attempt is enough for a display-only lookup — this must not
+      // stall triage/inbox rendering behind retry backoff.
+      retry: { maxAttempts: 1, baseDelayMs: 0, maxDelayMs: 0 },
+    });
+    const payload: PrincipalsResolveInput = { channel, value };
+    const result = await sdk.operator.invoke('principals.resolve', payload) as PrincipalsResolveOutput;
+    if (!result.known || !result.principal) return UNKNOWN_ATTRIBUTION;
+    const principal: ResolvedPrincipalSummary = {
+      id: result.principal.id,
+      name: result.principal.name,
+      kind: result.principal.kind,
+    };
+    return { known: true, label: formatPrincipalLabel(principal), principal };
+  } catch (error) {
+    return { ...UNKNOWN_ATTRIBUTION, error: summarizeError(error) };
+  }
+}

package/src/agent/prompt-context-receipts.ts

@@ -202,7 +202,11 @@ function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput)
   const projectContext = discoverProjectContextFiles(input.shellPaths);
   const projectContextPrompt = buildProjectContextPrompt(input.shellPaths) ?? '';
   const memoryRecords = resolveMemoryRecords(input);
-  const eligibleMemory = memoryRecords.filter(isPromptActiveMemory);
+  // Bound to one arg: Array.filter passes (element, index, array), and
+  // isPromptActiveMemory's second param is `now` — passing the callback bare
+  // would leak the array index in as `now`, breaking the temporal-validity
+  // check for every record past index 0.
+  const eligibleMemory = memoryRecords.filter((record) => isPromptActiveMemory(record));
   const memoryRanking = rankMemoryForTurn(input.memoryRegistry, eligibleMemory, input.turnText);
   const activeMemory = memoryRanking.records.slice(0, 10);
   const activeMemoryIds = new Set(activeMemory.map((record) => record.id));

package/src/agent/unified-inbox.ts

@@ -17,6 +17,7 @@
  */
 
 import type { AgentWorkspaceChannelTriage } from '../input/agent-workspace-channel-triage.ts';
+import { UNKNOWN_PRINCIPAL_LABEL } from './principal-attribution.ts';
 
 // ---------------------------------------------------------------------------
 // Item kinds
@@ -62,6 +63,10 @@ export interface UnifiedInboxRouteBindingItem {
   readonly surfaceId: string | null;
   /** External id is digested — never the raw identifier. */
   readonly externalIdDigest: string | null;
+  /** Resolved sender principal, when the channel identity maps to one. Never a guess. */
+  readonly principal: { readonly id: string; readonly name: string; readonly kind: string } | null;
+  /** Human-facing sender label — the resolved principal's "name (id)", or "unknown principal". */
+  readonly principalLabel: string;
   readonly sessionPolicy: string | null;
   readonly threadPolicy: string | null;
   readonly deliveryGuarantee: string | null;
@@ -202,6 +207,15 @@ function toSurfaceMessageItem(raw: Record<string, unknown>): UnifiedInboxSurface
   };
 }
 
+function toPrincipalOrNull(raw: Record<string, unknown>): { readonly id: string; readonly name: string; readonly kind: string } | null {
+  const principalRaw = isRecord(raw.principal) ? raw.principal : null;
+  if (!principalRaw) return null;
+  const id = readString(principalRaw, 'id');
+  const name = readString(principalRaw, 'name');
+  const kind = readString(principalRaw, 'kind');
+  return id && name && kind ? { id, name, kind } : null;
+}
+
 function toRouteBindingItem(raw: Record<string, unknown>): UnifiedInboxRouteBindingItem {
   return {
     kind: 'route_binding',
@@ -210,6 +224,8 @@ function toRouteBindingItem(raw: Record<string, unknown>): UnifiedInboxRouteBind
     surfaceKind: readString(raw, 'surfaceKind', 'unknown'),
     surfaceId: readStringOrNull(raw, 'surfaceId'),
     externalIdDigest: readStringOrNull(raw, 'externalIdDigest'),
+    principal: toPrincipalOrNull(raw),
+    principalLabel: readString(raw, 'principalLabel', UNKNOWN_PRINCIPAL_LABEL),
     sessionPolicy: readStringOrNull(raw, 'sessionPolicy'),
     threadPolicy: readStringOrNull(raw, 'threadPolicy'),
     deliveryGuarantee: readStringOrNull(raw, 'deliveryGuarantee'),
@@ -385,7 +401,7 @@ export function formatUnifiedInbox(inbox: UnifiedInbox): string {
   if (routeBindingItems.length > 0) {
     lines.push('', '  Route Bindings');
     for (const item of routeBindingItems.slice(0, 10)) {
-      lines.push(`  - ${item.id}: ${item.surfaceKind} ${item.bindingKind} ext=${item.externalIdDigest ?? 'none'}`);
+      lines.push(`  - ${item.id}: ${item.surfaceKind} ${item.bindingKind} ext=${item.externalIdDigest ?? 'none'} sender=${item.principalLabel}`);
     }
   }
 

package/src/cli/bundle-command.ts

@@ -16,6 +16,7 @@ import { classifyProviderSetup } from './provider-classification.ts';
 import { buildCliServicePosture } from './service-posture.ts';
 import { REDACTED_VALUE, collectSensitiveConfigValues, isRedactedValue, redactConfig, redactSerializedSecrets } from './redaction.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { appendTemporalLabel } from './temporal-label.ts';
 
 interface BundleInspectSummary {
   readonly type: string;
@@ -142,7 +143,7 @@ export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<C
         `  type: ${summary.type}`,
         `  version: ${summary.version}`,
         `  path: ${summary.path}`,
-        `  capturedAt: ${summary.capturedAt === null ? 'n/a' : new Date(summary.capturedAt).toISOString()}`,
+        `  capturedAt: ${summary.capturedAt === null ? 'n/a' : appendTemporalLabel(new Date(summary.capturedAt).toISOString(), summary.capturedAt)}`,
         `  configKeys: ${summary.configKeys}`,
         `  redactedConfigKeys: ${summary.redactedConfigPaths.length}`,
         `  diagnostics: ${summary.hasDiagnostics ? 'present' : 'missing'}`,

package/src/cli/channel-profiles-command.ts

@@ -0,0 +1,168 @@
+import type { OperatorMethodInput, OperatorMethodOutput } from '@pellux/goodvibes-sdk/contracts';
+import {
+  formatOperatorGatewayFailure,
+  invokeOperatorGatewayMethod,
+} from '../agent/operator-gateway-call.ts';
+import { resolveAgentConnectedHostConnection } from '../agent/routine-schedule-promotion.ts';
+import {
+  operatorFlagValue,
+  parseOperatorCommandArgs,
+} from './operator-command-args.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+import { appendTemporalLabel } from './temporal-label.ts';
+
+const CHANNEL_PROFILES_ROUTE = '/api/channels/profiles';
+const CHANNEL_PROFILE_ROUTE = '/api/channels/profiles/{surfaceKind}';
+
+const CHANNEL_PROFILES_GET_USAGE = 'Usage: goodvibes-agent channel-profiles get <surfaceKind> [--channel-id <id>]';
+const CHANNEL_PROFILES_SET_USAGE = 'Usage: goodvibes-agent channel-profiles set <surfaceKind> [--channel-id <id>] [--model <model>] [--provider <provider>] [--permission-mode <plan|normal|accept-edits|auto>] --yes';
+const CHANNEL_PROFILES_DELETE_USAGE = 'Usage: goodvibes-agent channel-profiles delete <surfaceKind> [--channel-id <id>] --yes';
+const CHANNEL_PROFILES_USAGE = 'Usage: goodvibes-agent channel-profiles [list|get <surfaceKind> [--channel-id <id>]|set <surfaceKind> [--channel-id <id>] [--model <model>] [--provider <provider>] [--permission-mode <mode>] --yes|delete <surfaceKind> [--channel-id <id>] --yes]';
+
+const PERMISSION_MODES = new Set(['plan', 'normal', 'accept-edits', 'auto']);
+
+type ChannelProfile = OperatorMethodOutput<'channels.profiles.list'>['bindings'][number];
+type PermissionMode = NonNullable<OperatorMethodInput<'channels.profiles.set'>['permissionMode']>;
+
+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_channel_profiles_command', error }, error),
+    exitCode: 2,
+  };
+}
+
+function parsePermissionMode(value: string | undefined, usage: string): PermissionMode | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (!PERMISSION_MODES.has(normalized)) throw new Error(`${usage}\n--permission-mode must be one of: plan, normal, accept-edits, auto.`);
+  return normalized as PermissionMode;
+}
+
+function renderChannelProfile(binding: ChannelProfile): string {
+  return [
+    `Channel profile ${binding.id}`,
+    `  surface ${binding.surfaceKind}${binding.channelId ? ` channel ${binding.channelId}` : ''}`,
+    `  model ${binding.model ?? '(default)'}`,
+    `  provider ${binding.provider ?? '(default)'}`,
+    `  permission mode ${binding.permissionMode ?? '(default)'}`,
+    `  updated ${appendTemporalLabel(new Date(binding.updatedAt).toISOString(), binding.updatedAt)}`,
+  ].join('\n');
+}
+
+function renderChannelProfileLine(binding: ChannelProfile): string {
+  const surface = binding.channelId ? `${binding.surfaceKind}:${binding.channelId}` : binding.surfaceKind;
+  return `  ${surface.padEnd(24)} model ${(binding.model ?? '(default)').padEnd(20)} provider ${(binding.provider ?? '(default)').padEnd(14)} permission ${binding.permissionMode ?? '(default)'}`;
+}
+
+function renderChannelProfileList(bindings: readonly ChannelProfile[]): string {
+  if (bindings.length === 0) {
+    return [
+      'Channel profiles',
+      '  No per-channel profile bindings configured yet.',
+      '  next goodvibes-agent channel-profiles set <surfaceKind> --model <model> --yes',
+    ].join('\n');
+  }
+  return [`Channel profiles (${bindings.length})`, ...bindings.map(renderChannelProfileLine)].join('\n');
+}
+
+async function handleChannelProfilesList(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'channels.profiles.list'>>(connection, 'channels.profiles.list', CHANNEL_PROFILES_ROUTE, {});
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return { output: jsonOrText(runtime, result, renderChannelProfileList(result.data.bindings)), exitCode: 0 };
+}
+
+async function handleChannelProfilesGet(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args, ['channel-id']);
+  const surfaceKind = parsed.positionals[0];
+  if (!surfaceKind) return usageFailure(runtime, CHANNEL_PROFILES_GET_USAGE);
+  const payload: OperatorMethodInput<'channels.profiles.get'> = {
+    surfaceKind,
+    channelId: operatorFlagValue(parsed, 'channel-id'),
+  };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'channels.profiles.get'>>(connection, 'channels.profiles.get', CHANNEL_PROFILE_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return { output: jsonOrText(runtime, result, renderChannelProfile(result.data.binding)), exitCode: 0 };
+}
+
+async function handleChannelProfilesSet(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args, ['channel-id', 'model', 'provider', 'permission-mode']);
+  const surfaceKind = parsed.positionals[0];
+  if (!surfaceKind) return usageFailure(runtime, CHANNEL_PROFILES_SET_USAGE);
+  let permissionMode: PermissionMode | undefined;
+  try {
+    permissionMode = parsePermissionMode(operatorFlagValue(parsed, 'permission-mode'), CHANNEL_PROFILES_SET_USAGE);
+  } catch (error) {
+    return usageFailure(runtime, error instanceof Error ? error.message : String(error));
+  }
+  if (!parsed.yes) {
+    return { output: `Refusing to set channel profile ${surfaceKind} without --yes.`, exitCode: 2 };
+  }
+  const payload: OperatorMethodInput<'channels.profiles.set'> = {
+    surfaceKind,
+    channelId: operatorFlagValue(parsed, 'channel-id'),
+    model: operatorFlagValue(parsed, 'model'),
+    provider: operatorFlagValue(parsed, 'provider'),
+    permissionMode,
+  };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'channels.profiles.set'>>(connection, 'channels.profiles.set', CHANNEL_PROFILES_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return {
+    output: jsonOrText(runtime, result, [`Set channel profile ${result.data.binding.id}`, renderChannelProfile(result.data.binding)].join('\n')),
+    exitCode: 0,
+  };
+}
+
+async function handleChannelProfilesDelete(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args, ['channel-id']);
+  const surfaceKind = parsed.positionals[0];
+  if (!surfaceKind) return usageFailure(runtime, CHANNEL_PROFILES_DELETE_USAGE);
+  if (!parsed.yes) {
+    return { output: `Refusing to delete channel profile ${surfaceKind} without --yes.`, exitCode: 2 };
+  }
+  const payload: OperatorMethodInput<'channels.profiles.delete'> = {
+    surfaceKind,
+    channelId: operatorFlagValue(parsed, 'channel-id'),
+  };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'channels.profiles.delete'>>(connection, 'channels.profiles.delete', CHANNEL_PROFILE_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return {
+    output: jsonOrText(runtime, result, `Deleted channel profile ${result.data.surfaceKind}${result.data.channelId ? `:${result.data.channelId}` : ''}: ${result.data.deleted ? 'ok' : 'not found'}`),
+    exitCode: result.data.deleted ? 0 : 1,
+  };
+}
+
+export async function handleChannelProfilesCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const [sub = 'list', ...rest] = runtime.cli.commandArgs;
+  switch (sub.toLowerCase()) {
+    case 'list':
+      return handleChannelProfilesList(runtime);
+    case 'get':
+    case 'show':
+      return handleChannelProfilesGet(runtime, rest);
+    case 'set':
+    case 'update':
+      return handleChannelProfilesSet(runtime, rest);
+    case 'delete':
+    case 'remove':
+      return handleChannelProfilesDelete(runtime, rest);
+    default:
+      return usageFailure(runtime, CHANNEL_PROFILES_USAGE);
+  }
+}

package/src/cli/ci-command.ts

@@ -0,0 +1,214 @@
+import type { OperatorMethodInput, OperatorMethodOutput } from '@pellux/goodvibes-sdk/contracts';
+import {
+  formatOperatorGatewayFailure,
+  invokeOperatorGatewayMethod,
+} from '../agent/operator-gateway-call.ts';
+import { resolveAgentConnectedHostConnection } from '../agent/routine-schedule-promotion.ts';
+import {
+  operatorFlagValue,
+  operatorHasFlag,
+  operatorParseIntFlag,
+  operatorRequiredFlag,
+  parseOperatorCommandArgs,
+} from './operator-command-args.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+import { appendTemporalLabel } from './temporal-label.ts';
+
+const CI_STATUS_ROUTE = '/api/ci/status';
+const CI_WATCHES_ROUTE = '/api/ci/watches';
+const CI_WATCH_ROUTE = '/api/ci/watches/{watchId}';
+const CI_WATCH_RUN_ROUTE = '/api/ci/watches/{watchId}/run';
+
+const CI_STATUS_USAGE = 'Usage: goodvibes-agent ci status <repo> [--ref <ref>] [--pr <number>]';
+const CI_WATCHES_CREATE_USAGE = 'Usage: goodvibes-agent ci watches create <repo> --delivery-channel <channel> [--ref <ref>] [--pr <number>] [--trigger-fix-session] --yes';
+const CI_WATCHES_DELETE_USAGE = 'Usage: goodvibes-agent ci watches delete <watchId> --yes';
+const CI_WATCHES_RUN_USAGE = 'Usage: goodvibes-agent ci watches run <watchId>';
+const CI_USAGE = 'Usage: goodvibes-agent ci [status <repo> [--ref <ref>] [--pr <number>]|watches list|watches create <repo> --delivery-channel <channel> [--ref <ref>] [--pr <number>] [--trigger-fix-session] --yes|watches delete <watchId> --yes|watches run <watchId>]';
+
+type CiReport = OperatorMethodOutput<'ci.status'>['report'];
+type CiWatch = OperatorMethodOutput<'ci.watches.list'>['watches'][number];
+
+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_ci_command', error }, error),
+    exitCode: 2,
+  };
+}
+
+function renderCiJobs(report: CiReport): readonly string[] {
+  if (report.jobs.length === 0) return ['  jobs (none reported)'];
+  return [
+    `  jobs (${report.jobs.length})`,
+    ...report.jobs.map((job) => {
+      const conclusion = job.conclusion ?? 'pending';
+      const continueOnError = job.continueOnError ? ' continue-on-error' : '';
+      return `    ${job.name.padEnd(32)} status ${job.status.padEnd(12)} conclusion ${conclusion}${continueOnError}`;
+    }),
+  ];
+}
+
+function renderCiReport(report: CiReport): string {
+  return [
+    `CI report ${report.repo}${report.ref ? ` @ ${report.ref}` : ''}${report.prNumber !== undefined ? ` PR #${report.prNumber}` : ''}`,
+    `  overall ${report.overall}`,
+    ...renderCiJobs(report),
+    report.violations.length > 0 ? `  violations: ${report.violations.join('; ')}` : '  violations: none',
+    `  checked at ${appendTemporalLabel(new Date(report.checkedAt).toISOString(), report.checkedAt)}`,
+  ].join('\n');
+}
+
+function renderCiWatch(watch: CiWatch): string {
+  return [
+    `  ${watch.id}  ${watch.repo}${watch.ref ? ` @ ${watch.ref}` : ''}${watch.prNumber !== undefined ? ` PR #${watch.prNumber}` : ''}`,
+    `    delivery ${watch.deliveryChannel}  trigger-fix-session ${watch.triggerFixSession ? 'yes' : 'no'}  last overall ${watch.lastOverall ?? 'unknown'}`,
+  ].join('\n');
+}
+
+function renderCiWatchList(watches: readonly CiWatch[]): string {
+  if (watches.length === 0) {
+    return [
+      'CI watches',
+      '  No CI watches configured yet.',
+      '  next goodvibes-agent ci watches create <repo> --delivery-channel <channel> --yes',
+    ].join('\n');
+  }
+  return [`CI watches (${watches.length})`, ...watches.map(renderCiWatch)].join('\n');
+}
+
+async function handleCiStatus(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args, ['ref', 'pr']);
+  const repo = parsed.positionals[0];
+  if (!repo) return usageFailure(runtime, CI_STATUS_USAGE);
+  let prNumber: number | undefined;
+  try {
+    prNumber = operatorParseIntFlag(parsed, 'pr', CI_STATUS_USAGE);
+  } catch (error) {
+    return usageFailure(runtime, error instanceof Error ? error.message : String(error));
+  }
+  const payload: OperatorMethodInput<'ci.status'> = {
+    repo,
+    ref: operatorFlagValue(parsed, 'ref'),
+    prNumber,
+  };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'ci.status'>>(connection, 'ci.status', CI_STATUS_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return { output: jsonOrText(runtime, result, renderCiReport(result.data.report)), exitCode: 0 };
+}
+
+async function handleCiWatchesList(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'ci.watches.list'>>(connection, 'ci.watches.list', CI_WATCHES_ROUTE, {});
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return { output: jsonOrText(runtime, result, renderCiWatchList(result.data.watches)), exitCode: 0 };
+}
+
+async function handleCiWatchesCreate(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args, ['ref', 'pr', 'delivery-channel']);
+  const repo = parsed.positionals[0];
+  if (!repo) return usageFailure(runtime, CI_WATCHES_CREATE_USAGE);
+  let deliveryChannel: string;
+  let prNumber: number | undefined;
+  try {
+    deliveryChannel = operatorRequiredFlag(parsed, 'delivery-channel', CI_WATCHES_CREATE_USAGE);
+    prNumber = operatorParseIntFlag(parsed, 'pr', CI_WATCHES_CREATE_USAGE);
+  } catch (error) {
+    return usageFailure(runtime, error instanceof Error ? error.message : String(error));
+  }
+  if (!parsed.yes) {
+    return { output: `Refusing to create a CI watch for ${repo} without --yes.`, exitCode: 2 };
+  }
+  const payload: OperatorMethodInput<'ci.watches.create'> = {
+    repo,
+    ref: operatorFlagValue(parsed, 'ref'),
+    prNumber,
+    deliveryChannel,
+    triggerFixSession: operatorHasFlag(parsed, 'trigger-fix-session') || undefined,
+  };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'ci.watches.create'>>(connection, 'ci.watches.create', CI_WATCHES_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return {
+    output: jsonOrText(runtime, result, [`Created CI watch ${result.data.watch.id}`, renderCiWatch(result.data.watch)].join('\n')),
+    exitCode: 0,
+  };
+}
+
+async function handleCiWatchesDelete(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args);
+  const watchId = parsed.positionals[0];
+  if (!watchId) return usageFailure(runtime, CI_WATCHES_DELETE_USAGE);
+  if (!parsed.yes) {
+    return { output: `Refusing to delete CI watch ${watchId} without --yes.`, exitCode: 2 };
+  }
+  const payload: OperatorMethodInput<'ci.watches.delete'> = { watchId };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'ci.watches.delete'>>(connection, 'ci.watches.delete', CI_WATCH_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return {
+    output: jsonOrText(runtime, result, `Deleted CI watch ${result.data.watchId}: ${result.data.deleted ? 'ok' : 'not found'}`),
+    exitCode: result.data.deleted ? 0 : 1,
+  };
+}
+
+async function handleCiWatchesRun(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const parsed = parseOperatorCommandArgs(args);
+  const watchId = parsed.positionals[0];
+  if (!watchId) return usageFailure(runtime, CI_WATCHES_RUN_USAGE);
+  const payload: OperatorMethodInput<'ci.watches.run'> = { watchId };
+  const connection = resolveAgentConnectedHostConnection(runtime.configManager, runtime.homeDirectory);
+  const result = await invokeOperatorGatewayMethod<OperatorMethodOutput<'ci.watches.run'>>(connection, 'ci.watches.run', CI_WATCH_RUN_ROUTE, payload);
+  if (!result.ok) {
+    return { output: jsonOrText(runtime, result, formatOperatorGatewayFailure(result)), exitCode: 1 };
+  }
+  return {
+    output: jsonOrText(runtime, result, [
+      renderCiReport(result.data.report),
+      `  notified ${result.data.notified ? 'yes' : 'no'}${result.data.notificationId ? ` (${result.data.notificationId})` : ''}`,
+      `  fix session triggered ${result.data.fixSessionTriggered ? 'yes' : 'no'}${result.data.fixSessionId ? ` (${result.data.fixSessionId})` : ''}`,
+    ].join('\n')),
+    exitCode: 0,
+  };
+}
+
+async function handleCiWatchesCommand(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const [sub = 'list', ...rest] = args;
+  switch (sub.toLowerCase()) {
+    case 'list':
+      return handleCiWatchesList(runtime);
+    case 'create':
+      return handleCiWatchesCreate(runtime, rest);
+    case 'delete':
+    case 'remove':
+      return handleCiWatchesDelete(runtime, rest);
+    case 'run':
+      return handleCiWatchesRun(runtime, rest);
+    default:
+      return usageFailure(runtime, CI_USAGE);
+  }
+}
+
+export async function handleCiCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const [sub, ...rest] = runtime.cli.commandArgs;
+  switch ((sub ?? '').toLowerCase()) {
+    case 'status':
+      return handleCiStatus(runtime, rest);
+    case 'watches':
+      return handleCiWatchesCommand(runtime, rest);
+    default:
+      return usageFailure(runtime, CI_USAGE);
+  }
+}

package/src/cli/completion.ts

@@ -9,6 +9,11 @@ const COMMANDS = [
   'providers',
   'profiles',
   'routines',
+  'ci',
+  'principals',
+  'channel-profiles',
+  'workspaces',
+  'fleet',
   'auth',
   'compat',
   'knowledge',