@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-harness-ui-surface-metadata.ts

@@ -1,58 +1,17 @@
 import type { CommandContext } from '../input/command-registry.ts';
 import { openTtsProviderPicker, openTtsVoicePicker } from '../input/tts-settings-actions.ts';
+import { openExternalUrl } from '@pellux/goodvibes-sdk/platform/utils';
+import { connectedBrowserCockpitRoute } from './agent-harness-browser-cockpit-route.ts';
+import type { AgentHarnessUiSurfaceArgs, UiSurfaceDefinition, UiSurfaceLookup, UiSurfaceResolution } from './agent-harness-ui-surface-types.ts';
+export type { AgentHarnessUiSurfaceArgs } from './agent-harness-ui-surface-types.ts';
 
-type UiSurfaceKind = 'overlay' | 'modal' | 'workspace' | 'picker';
+function agentHarnessModes(...modes: readonly string[]): string { return `agent_harness ${modes.map((mode) => `mode:"${mode}"`).join(', ')}`; }
 
-function agentHarnessModes(...modes: readonly string[]): string {
-  return `agent_harness ${modes.map((mode) => `mode:"${mode}"`).join(', ')}`;
-}
+function settingsActions(...actions: readonly string[]): string { return `settings ${actions.map((action) => `action:"${action}"`).join('|')}`; }
 
-export interface AgentHarnessUiSurfaceArgs {
-  readonly query?: unknown;
-  readonly surfaceId?: unknown;
-  readonly categoryId?: unknown;
-  readonly category?: unknown;
-  readonly target?: unknown;
-  readonly key?: unknown;
-  readonly prefix?: unknown;
-  readonly includeParameters?: unknown;
-  readonly limit?: unknown;
-  readonly pane?: unknown;
-}
+function hostActions(...actions: readonly string[]): string { return `host ${actions.map((action) => `action:"${action}"`).join('|')}`; }
 
-interface UiSurfaceDefinition {
-  readonly id: string;
-  readonly label: string;
-  readonly kind: UiSurfaceKind;
-  readonly summary: string;
-  readonly command: string;
-  readonly preferredModelRoute: string;
-  readonly parameters?: readonly string[];
-  readonly available: (context: CommandContext) => boolean;
-  readonly open: (context: CommandContext, args: AgentHarnessUiSurfaceArgs) => Record<string, unknown> | Promise<Record<string, unknown>>;
-}
-
-interface UiSurfaceLookup {
-  readonly source: 'surfaceId' | 'target' | 'query';
-  readonly input: string;
-  readonly resolvedBy: 'id' | 'case-insensitive-id' | 'label' | 'case-insensitive-label' | 'search';
-}
-
-type UiSurfaceResolution =
-  | {
-    readonly status: 'found';
-    readonly surface: UiSurfaceDefinition;
-    readonly lookup: UiSurfaceLookup;
-  }
-  | {
-    readonly status: 'ambiguous';
-    readonly input: string;
-    readonly candidates: readonly Record<string, unknown>[];
-  };
-
-function readString(value: unknown): string {
-  return typeof value === 'string' ? value.trim() : '';
-}
+function readString(value: unknown): string { return typeof value === 'string' ? value.trim() : ''; }
 
 function readLimit(value: unknown, fallback: number): number {
   const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
@@ -181,6 +140,47 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
       return opened(surface, { categoryId: categoryId ?? 'default' });
     },
   },
+  {
+    id: 'connected-browser-cockpit',
+    label: 'Connected Browser Cockpit',
+    kind: 'workspace',
+    summary: 'Connected-host browser cockpit/PWA route.',
+    command: 'connected host web route',
+    preferredModelRoute: `Use ${hostActions('service', 'services', 'status')} or ${settingsActions('list', 'get')} to inspect or repair web readiness; use mode:"open_ui_surface" only to visibly open the configured cockpit URL.`,
+    available: (context) => {
+      try {
+        return context.platform?.configManager?.get?.('web.enabled') === true;
+      } catch {
+        return false;
+      }
+    },
+    open: async (context) => {
+      const surface = findSurfaceById('connected-browser-cockpit')!;
+      const route = connectedBrowserCockpitRoute(context);
+      if (route.enabled !== true) {
+        return {
+          status: 'setup_needed',
+          surface: surface.id,
+          kind: surface.kind,
+          route,
+          note: 'The connected-host web endpoint is disabled. Inspect service posture or web settings before opening a browser cockpit.',
+        };
+      }
+      const url = typeof route.url === 'string' ? route.url : '';
+      const browserOpened = url ? await openExternalUrl(url) : false;
+      return browserOpened
+        ? opened(surface, { url, route, browserOpened })
+        : {
+          status: 'open_failed',
+          surface: surface.id,
+          kind: surface.kind,
+          url,
+          route,
+          browserOpened,
+          note: 'The configured browser cockpit URL was resolved, but the external browser opener did not report success.',
+        };
+    },
+  },
   {
     id: 'panel-picker',
     label: 'Panel Picker',
@@ -258,7 +258,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'modal',
     summary: 'Fullscreen settings workspace for Agent config, secrets, MCP, and tools.',
     command: '/settings',
-    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
+    preferredModelRoute: `Use ${settingsActions('list', 'get', 'set', 'reset', 'import')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['target', 'key', 'prefix'],
     available: (context) => typeof context.openSettingsModal === 'function',
     open: (context, args) => {
@@ -275,7 +275,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'MCP server setup, trust posture, and tool inventory workspace.',
     command: '/mcp',
-    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'tools', 'settings')} for model operation.`,
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'tools')} or ${settingsActions('list', 'get', 'set')} for model operation.`,
     available: (context) => typeof context.openMcpWorkspace === 'function',
     open: (context) => openSimpleContextSurface(context, 'mcp-workspace', 'openMcpWorkspace'),
   },
@@ -285,7 +285,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive model picker for main, helper, tool, and TTS model routes.',
     command: '/model',
-    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for direct provider.model changes, or mode:"run_command" with confirmation when a concrete model id is known.`,
+    preferredModelRoute: `Use ${settingsActions('get', 'set')} for direct provider.model changes, or mode:"run_command" with confirmation when a concrete model id is known.`,
     parameters: ['target'],
     available: (context) => typeof context.openModelPicker === 'function' || typeof context.openModelPickerWithTarget === 'function',
     open: (context, args) => {
@@ -306,7 +306,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive provider picker for model route setup.',
     command: '/provider',
-    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for direct provider routing changes, or confirmed mode:"run_command" mirrors for concrete provider changes.`,
+    preferredModelRoute: `Use ${settingsActions('get', 'set')} for direct provider routing changes, or confirmed mode:"run_command" mirrors for concrete provider changes.`,
     parameters: ['target'],
     available: (context) => typeof context.openProviderPicker === 'function' || typeof context.openProviderModelPickerWithTarget === 'function',
     open: (context, args) => {
@@ -327,7 +327,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Reasoning-effort selector for models that expose effort levels.',
     command: '/effort',
-    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for provider.reasoningEffort when a concrete level is known, or mode:"run_workspace_action" setup-reasoning-effort with confirmation.`,
+    preferredModelRoute: `Use ${settingsActions('get', 'set')} for provider.reasoningEffort when a concrete level is known, or mode:"run_workspace_action" setup-reasoning-effort with confirmation.`,
     available: (context) => typeof context.openReasoningEffortPicker === 'function',
     open: (context) => {
       const surface = findSurfaceById('reasoning-effort-picker')!;
@@ -355,7 +355,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Streaming TTS provider picker from Agent settings.',
     command: '/config tts.provider',
-    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for tts.provider when a concrete provider id is known; use mode:"open_ui_surface" only to visibly navigate.`,
+    preferredModelRoute: `Use ${settingsActions('get', 'set')} for tts.provider when a concrete provider id is known; use mode:"open_ui_surface" only to visibly navigate.`,
     available: (context) => typeof context.openSelection === 'function' && Boolean(context.platform.voiceProviderRegistry),
     open: (context) => {
       const surface = findSurfaceById('tts-provider-picker')!;
@@ -370,7 +370,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'TTS voice picker for the selected or supplied provider.',
     command: '/config tts.voice',
-    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} for tts.voice when a concrete voice id is known; use mode:"open_ui_surface" only to visibly navigate.`,
+    preferredModelRoute: `Use ${settingsActions('get', 'set', 'reset')} for tts.voice when a concrete voice id is known; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['target'],
     available: (context) => typeof context.openSelection === 'function' && Boolean(context.platform.voiceService),
     open: async (context, args) => {
@@ -613,7 +613,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'Agent workspace entry for first-run and setup review.',
     command: '/agent',
-    preferredModelRoute: `Use ${agentHarnessModes('workspace', 'workspace_actions', 'settings')} for concrete setup operation.`,
+    preferredModelRoute: `Use ${agentHarnessModes('workspace', 'workspace_actions')} or ${settingsActions('list', 'get', 'set')} for concrete setup operation.`,
     available: (context) => typeof context.openAgentWorkspace === 'function',
     open: (context) => {
       const surface = findSurfaceById('onboarding')!;
@@ -630,7 +630,7 @@ function findSurfaceById(surfaceId: string): UiSurfaceDefinition | undefined {
 
 function surfaceMatches(surface: Record<string, unknown>, query: string): boolean {
   if (!query) return true;
-  return [
+  const haystack = [
     surface.id,
     surface.label,
     surface.kind,
@@ -638,7 +638,11 @@ function surfaceMatches(surface: Record<string, unknown>, query: string): boolea
     surface.command,
     surface.modelRoute,
     surface.preferredModelRoute,
-  ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
+  ].map((value) => String(value ?? '')).join('\n').toLowerCase();
+  const normalized = query.toLowerCase().trim();
+  if (haystack.includes(normalized)) return true;
+  const tokens = normalized.split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+  return tokens.length > 0 && tokens.every((token) => haystack.includes(token));
 }
 
 function surfaceLookupFromArgs(args: AgentHarnessUiSurfaceArgs): { readonly source: UiSurfaceLookup['source']; readonly input: string } | null {
@@ -664,43 +668,45 @@ function surfaceCandidate(surface: UiSurfaceDefinition): Record<string, unknown>
 
 function uiSurfaceModelRoute(surface: UiSurfaceDefinition): string {
   switch (surface.id) {
+    case 'connected-browser-cockpit':
+      return 'computer action:"browser|open_browser" or workspace action:"open"';
     case 'agent-workspace':
     case 'panel-picker':
     case 'security-panel':
     case 'subscription-panel':
     case 'mcp-workspace':
     case 'onboarding':
-      return 'agent_harness mode:"workspace_actions" or mode:"open_ui_surface"';
+      return 'workspace action:"actions|open"';
     case 'knowledge-panel':
-      return 'agent_knowledge, agent_knowledge_ingest, or workspace_actions';
+      return 'agent_knowledge, agent_knowledge_ingest, or workspace action:"actions"';
     case 'settings':
     case 'tts-provider-picker':
     case 'tts-voice-picker':
     case 'reasoning-effort-picker':
-      return 'agent_harness mode:"settings" or mode:"open_ui_surface"';
+      return 'settings action:"list|get|set" or workspace action:"open"';
     case 'model-picker':
     case 'provider-picker':
-      return 'agent_harness mode:"settings" or mode:"run_command"';
+      return 'settings action:"get|set" or workspace action:"run_command"';
     case 'session-picker':
     case 'bookmark-modal':
     case 'context-inspector':
     case 'slash-command-mode':
     case 'command-browser':
     case 'block-actions':
-      return 'agent_harness mode:"commands" or mode:"run_command"';
+      return 'workspace action:"commands|run_command"';
     case 'process-monitor':
     case 'live-tail':
     case 'file-picker':
-      return 'first-class tools or agent_harness mode:"open_ui_surface"';
+      return 'first-class tools or workspace action:"open"';
     case 'conversation-search':
     case 'prompt-history-search':
-      return 'agent_harness mode:"open_ui_surface"';
+      return 'workspace action:"open"';
     case 'help-overlay':
-      return 'agent_harness mode:"commands" or mode:"shortcuts"';
+      return 'workspace action:"commands|shortcuts"';
     case 'shortcuts-overlay':
-      return 'agent_harness mode:"shortcuts" or mode:"keybindings"';
+      return 'workspace action:"shortcuts|keybindings"';
     default:
-      return 'agent_harness mode:"open_ui_surface"';
+      return 'workspace action:"open"';
   }
 }
 
@@ -738,6 +744,7 @@ function describeSurface(
     ...(options.lookup ? { lookup: options.lookup } : {}),
     modelRoute: uiSurfaceModelRoute(surface),
     available: surface.available(context),
+    ...(surface.id === 'connected-browser-cockpit' ? { cockpit: connectedBrowserCockpitRoute(context, { includeWorkspaceCoverage: options.includeParameters === true }) } : {}),
     ...(options.includeParameters ? {
       preferredModelRoute: surface.preferredModelRoute,
       parameters: surface.parameters ?? [],

package/src/tools/agent-harness-ui-surface-types.ts

@@ -0,0 +1,46 @@
+import type { CommandContext } from '../input/command-registry.ts';
+
+export type UiSurfaceKind = 'overlay' | 'modal' | 'workspace' | 'picker';
+
+export interface AgentHarnessUiSurfaceArgs {
+  readonly query?: unknown;
+  readonly surfaceId?: unknown;
+  readonly categoryId?: unknown;
+  readonly category?: unknown;
+  readonly target?: unknown;
+  readonly key?: unknown;
+  readonly prefix?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+  readonly pane?: unknown;
+}
+
+export interface UiSurfaceDefinition {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: UiSurfaceKind;
+  readonly summary: string;
+  readonly command: string;
+  readonly preferredModelRoute: string;
+  readonly parameters?: readonly string[];
+  readonly available: (context: CommandContext) => boolean;
+  readonly open: (context: CommandContext, args: AgentHarnessUiSurfaceArgs) => Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+
+export interface UiSurfaceLookup {
+  readonly source: 'surfaceId' | 'target' | 'query';
+  readonly input: string;
+  readonly resolvedBy: 'id' | 'case-insensitive-id' | 'label' | 'case-insensitive-label' | 'search';
+}
+
+export type UiSurfaceResolution =
+  | {
+    readonly status: 'found';
+    readonly surface: UiSurfaceDefinition;
+    readonly lookup: UiSurfaceLookup;
+  }
+  | {
+    readonly status: 'ambiguous';
+    readonly input: string;
+    readonly candidates: readonly Record<string, unknown>[];
+  };

package/src/tools/agent-harness-vibe-health.ts

@@ -0,0 +1,105 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import type { AgentVibeFile, BlockedAgentVibeFile } from '../agent/vibe-file.ts';
+import { discoverVibeFiles } from '../agent/vibe-file.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+
+export interface AgentHarnessVibeHealthFile {
+  readonly path: string;
+  readonly scope: string;
+  readonly truncated?: boolean;
+}
+
+export interface AgentHarnessVibeHealthBlockedFile {
+  readonly path: string;
+  readonly scope: string;
+  readonly reason: string;
+}
+
+export interface AgentHarnessVibeHealth {
+  readonly status: 'ready' | 'check' | 'recommended';
+  readonly applied: number;
+  readonly blocked: number;
+  readonly truncated: number;
+  readonly files: readonly AgentHarnessVibeHealthFile[];
+  readonly blockedFiles: readonly AgentHarnessVibeHealthBlockedFile[];
+  readonly searchedPaths: readonly string[];
+  readonly projectInitPath: string;
+  readonly globalInitPath: string;
+  readonly nextAction: string;
+  readonly userRoute: string;
+  readonly modelRoute: string;
+  readonly signals: readonly string[];
+}
+
+function describeVibeFile(file: AgentVibeFile): AgentHarnessVibeHealthFile {
+  return {
+    path: file.path,
+    scope: file.scope,
+    ...(file.truncated ? { truncated: true } : {}),
+  };
+}
+
+function describeBlockedVibeFile(file: BlockedAgentVibeFile): AgentHarnessVibeHealthBlockedFile {
+  return {
+    path: file.path,
+    scope: file.scope,
+    reason: previewHarnessText(file.reason, 180),
+  };
+}
+
+export function agentHarnessVibeHealth(context: CommandContext): AgentHarnessVibeHealth {
+  const shellPaths = context.workspace.shellPaths;
+  if (!shellPaths) {
+    return {
+      status: 'recommended',
+      applied: 0,
+      blocked: 0,
+      truncated: 0,
+      files: [],
+      blockedFiles: [],
+      searchedPaths: [],
+      projectInitPath: '',
+      globalInitPath: '',
+      nextAction: 'VIBE.md discovery is unavailable because shell paths are not wired into this runtime.',
+      userRoute: 'Agent Workspace -> Local Context -> Personas -> VIBE.md; /vibe status',
+      modelRoute: 'vibe action:"status"',
+      signals: ['VIBE.md discovery unavailable: shell paths are not wired.'],
+    };
+  }
+  const snapshot = discoverVibeFiles(shellPaths);
+  const truncated = snapshot.files.filter((file) => file.truncated);
+  const status = snapshot.blocked.length > 0 || truncated.length > 0
+    ? 'check'
+    : snapshot.files.length > 0
+      ? 'ready'
+      : 'recommended';
+  const nextAction = snapshot.blocked.length > 0
+    ? 'Run /vibe status, inspect blocked files, and edit or remove secret-looking content before relying on personality instructions.'
+    : truncated.length > 0
+      ? 'Run /vibe status and shorten the truncated VIBE.md file if the omitted content matters.'
+      : snapshot.files.length > 0
+        ? 'Review /vibe status when changing project or global personality instructions.'
+        : 'Create a project VIBE.md or import a reviewed persona when the user wants a custom assistant feel.';
+  const signals = [
+    `applied VIBE.md files: ${snapshot.files.length}`,
+    `blocked VIBE.md files: ${snapshot.blocked.length}`,
+    `truncated VIBE.md files: ${truncated.length}`,
+    ...(snapshot.files.slice(0, 3).map((file) => `${file.scope}: ${file.path}${file.truncated ? ' (truncated)' : ''}`)),
+    ...(snapshot.blocked.slice(0, 3).map((file) => `blocked ${file.scope}: ${file.path} - ${previewHarnessText(file.reason, 96)}`)),
+  ];
+  return {
+    status,
+    applied: snapshot.files.length,
+    blocked: snapshot.blocked.length,
+    truncated: truncated.length,
+    files: snapshot.files.map(describeVibeFile),
+    blockedFiles: snapshot.blocked.map(describeBlockedVibeFile),
+    searchedPaths: snapshot.searchedPaths,
+    projectInitPath: snapshot.projectInitPath,
+    globalInitPath: snapshot.globalInitPath,
+    nextAction,
+    userRoute: 'Agent Workspace -> Local Context -> Personas -> VIBE.md; /vibe status',
+    modelRoute: 'vibe action:"status"',
+    signals,
+  };
+}

package/src/tools/agent-harness-workspace-action-runner.ts

@@ -0,0 +1,149 @@
+import type { AgentHarnessToolArgs, AgentHarnessToolDeps } from './agent-harness-tool-types.ts';
+import { clearSetupCheckpoint, markSetupCheckpoint, setupCheckpointSummary } from './agent-harness-setup-posture.ts';
+import { runLocalWorkspaceAction } from './agent-harness-local-operations.ts';
+import { AGENT_WORKSPACE_CATEGORIES, buildWorkspaceEditorContext, createWorkspaceEditor, describeWorkspaceAction, describeWorkspaceCategory, listWorkspaceActions, resolveWorkspaceActionDetail } from './agent-harness-workspace-actions.ts';
+import { runCommand } from './agent-harness-command-runner.ts';
+import { runWorkspaceEditorAction } from './agent-harness-workspace-editor-runner.ts';
+import { error, output, readString, requireConfirmedAction } from './agent-harness-tool-utils.ts';
+import { importAgentWorkspaceTuiSettings, previewAgentWorkspaceTuiSettingsImport } from '../input/agent-workspace-settings.ts';
+import { writeOnboardingCheckMarker, writeOnboardingCompletionMarker } from '../runtime/onboarding/index.ts';
+
+export async function runWorkspaceAction(
+  deps: AgentHarnessToolDeps,
+  args: AgentHarnessToolArgs,
+): Promise<{ readonly success: boolean; readonly output?: string; readonly error?: string }> {
+  const resolved = resolveWorkspaceActionDetail(args);
+  if (resolved?.status === 'ambiguous') return error(`Ambiguous Agent workspace action ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  if (!resolved) return error('run_workspace_action requires a valid actionId, command, target, or query. Use mode:"workspace_actions" to inspect available actions.');
+  const { category, action, lookup } = resolved;
+
+  if (action.safety === 'blocked') {
+    return error(`Workspace action ${action.id} is blocked in Agent: ${action.detail}`);
+  }
+  if (action.kind === 'guidance') {
+    const editorContext = buildWorkspaceEditorContext(deps.commandContext, args);
+    return output({
+      status: 'guidance',
+      action: describeWorkspaceAction(category, action, { includeEditor: true, editorContext, lookup }),
+    });
+  }
+  if (action.kind === 'workspace' && action.targetCategoryId) {
+    const target = AGENT_WORKSPACE_CATEGORIES.find((entry) => entry.id === action.targetCategoryId);
+    return output({
+      status: 'workspace_target',
+      action: describeWorkspaceAction(category, action, { lookup }),
+      targetCategory: target ? describeWorkspaceCategory(target) : action.targetCategoryId,
+      targetActions: target ? target.actions.map((entry) => describeWorkspaceAction(target, entry)).slice(0, 40) : [],
+    });
+  }
+  if (action.kind === 'command' && action.command) {
+    if (/<[^>\s]+(?:\s+[^>]*)?>/.test(action.command)) {
+      return output({
+        status: 'needs_concrete_command',
+        action: describeWorkspaceAction(category, action, { lookup }),
+        note: 'This workspace action is a command template. Provide concrete values with mode:"run_command" once the exact command is known.',
+      });
+    }
+    return runCommand(deps, { ...args, command: action.command });
+  }
+  if (action.kind === 'settings-import') {
+    const preview = previewAgentWorkspaceTuiSettingsImport(deps.commandContext);
+    if (!preview) return error('GoodVibes settings import is unavailable in this runtime.');
+    if (args.confirm !== true) {
+      return output({
+        status: 'confirmation_required',
+        action: describeWorkspaceAction(category, action, { lookup }),
+        preview,
+        next: 'Run with confirm:true and explicitUserRequest after the user asks to import these settings.',
+      });
+    }
+    const explicitUserRequest = readString(args.explicitUserRequest);
+    if (!explicitUserRequest) {
+      return error('GoodVibes settings import requires explicitUserRequest when confirm is true.');
+    }
+    const outcome = await importAgentWorkspaceTuiSettings(deps.commandContext);
+    return output({
+      status: outcome.status,
+      action: describeWorkspaceAction(category, action, { lookup }),
+      preview,
+      actionResult: outcome.result,
+      runtimeSnapshot: outcome.runtimeSnapshot,
+      policy: {
+        effect: 'state',
+        confirmation: 'confirmed',
+        explicitUserRequest,
+        boundary: 'Applied only Agent-owned settings and subscription state from published GoodVibes platform sources; source package stores were not mutated.',
+      },
+    });
+  }
+  if (action.kind === 'setup-checkpoint') {
+    const operation = action.setupCheckpointOperation ?? 'show';
+    if (operation === 'show') {
+      return output({
+        status: 'checkpoint_inspected',
+        action: describeWorkspaceAction(category, action, { lookup }),
+        checkpoint: await setupCheckpointSummary(deps.commandContext),
+      });
+    }
+    const confirmationError = requireConfirmedAction(args, operation === 'clear' ? 'Setup wizard checkpoint clear' : 'Setup wizard checkpoint save');
+    if (confirmationError) return error(confirmationError);
+    const result = operation === 'clear'
+      ? clearSetupCheckpoint(deps.commandContext, args)
+      : await markSetupCheckpoint(deps.commandContext, args);
+    return output({
+      status: 'checkpoint_action_completed',
+      action: describeWorkspaceAction(category, action, { lookup }),
+      result,
+    });
+  }
+  if (action.kind === 'editor' && action.editorKind) {
+    const editor = createWorkspaceEditor(action.editorKind, buildWorkspaceEditorContext(deps.commandContext, args));
+    if (!editor) return error(`No workspace editor route exists for ${action.editorKind}.`);
+    return runWorkspaceEditorAction(deps, action, editor, args);
+  }
+  if (action.kind === 'local-selection' || action.kind === 'local-operation') {
+    return runLocalWorkspaceAction(deps, action, args);
+  }
+  if (action.kind === 'onboarding-complete') {
+    const confirmationError = requireConfirmedAction(args, 'Onboarding completion');
+    if (confirmationError) return error(confirmationError);
+    const explicitUserRequest = readString(args.explicitUserRequest);
+    if (!explicitUserRequest) return error('Onboarding completion requires explicitUserRequest when confirm is true.');
+    const shellPaths = deps.commandContext.workspace?.shellPaths;
+    if (!shellPaths) return error('Onboarding completion requires Agent shell paths.');
+    const marker = { scope: 'user', source: 'wizard', mode: 'new', workspaceRoot: shellPaths.workingDirectory } as const;
+    const checkMarker = writeOnboardingCheckMarker(shellPaths, marker);
+    const completionMarker = writeOnboardingCompletionMarker(shellPaths, marker);
+    return output({
+      status: 'onboarding_completed',
+      action: describeWorkspaceAction(category, action, { lookup }),
+      explicitUserRequest,
+      checkMarker: {
+        exists: checkMarker.exists,
+        path: checkMarker.path,
+        updatedAt: checkMarker.payload?.updatedAt ?? null,
+        source: checkMarker.payload?.source ?? null,
+        mode: checkMarker.payload?.mode ?? null,
+      },
+      completionMarker: {
+        exists: completionMarker.exists,
+        path: completionMarker.path,
+        updatedAt: completionMarker.payload?.updatedAt ?? null,
+        source: completionMarker.payload?.source ?? null,
+        mode: completionMarker.payload?.mode ?? null,
+      },
+      routes: {
+        inspectSetup: 'setup action:"status" includeParameters:true',
+      },
+      policy: {
+        effect: 'confirmed-onboarding-marker-write',
+        boundary: 'Writes only the user onboarding check and completion markers. It does not mutate provider credentials, connected-host state, channels, schedules, or local behavior.',
+      },
+    });
+  }
+  const editorContext = buildWorkspaceEditorContext(deps.commandContext, args);
+  return output({
+    status: 'no_direct_effect',
+    action: describeWorkspaceAction(category, action, { includeEditor: true, editorContext, lookup }),
+  });
+}