fix(console): clarify Pilot Agent host-console unavailability (#1868)

Replace the generic upgrade message on Pilot Agent nodes with transport-specific
copy while preserving DAP-remote behavior.

- Add resolveHostConsoleLockMessage() to return Pilot-specific copy when
  nodeMode === 'pilot_agent'; otherwise keep generic upgrade message.
- Update ViewRouter to use the helper in the locked branch.
- Add unit tests for the new helper and component behavior.
- Sync docs/features/host-console.mdx to reflect the Pilot Agent message.

Closes #1855

frontend/src/lib/routing/hostConsoleCapability.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { resolveHostConsoleCapability } from './hostConsoleCapability';
+import { resolveHostConsoleCapability, resolveHostConsoleLockMessage } from './hostConsoleCapability';
 
 describe('resolveHostConsoleCapability', () => {
   it('returns loading when the active node is unresolved', () => {
@@ -92,3 +92,60 @@ describe('resolveHostConsoleCapability', () => {
     })).toBe('locked');
   });
 });
+
+describe('resolveHostConsoleLockMessage', () => {
+  it('returns Pilot-specific copy for a pilot_agent node regardless of version', () => {
+    expect(resolveHostConsoleLockMessage({
+      nodeMode: 'pilot_agent',
+      nodeName: 'Pilot',
+      version: '0.97.1',
+    })).toEqual({
+      title: 'Host Console is not available through Pilot Agent yet',
+      body: 'Host Console is currently available on the local node and Distributed API Proxy remotes.',
+    });
+  });
+
+  it('returns the upgrade copy for a proxy node with a real version', () => {
+    expect(resolveHostConsoleLockMessage({
+      nodeMode: 'proxy',
+      nodeName: 'Peer',
+      version: '0.95.0',
+    })).toEqual({
+      title: 'Host Console is not available on this node',
+      body: 'Peer is running v0.95.0. Upgrade the node to use this feature.',
+    });
+  });
+
+  it('returns the no-capability copy for a proxy node with a placeholder version', () => {
+    expect(resolveHostConsoleLockMessage({
+      nodeMode: 'proxy',
+      nodeName: 'Peer',
+      version: '0.0.0-dev',
+    })).toEqual({
+      title: 'Host Console is not available on this node',
+      body: 'Peer does not advertise this capability. Upgrade the node to use this feature.',
+    });
+  });
+
+  it('returns the no-capability copy for a proxy node with an unknown version', () => {
+    expect(resolveHostConsoleLockMessage({
+      nodeMode: 'proxy',
+      nodeName: 'Peer',
+      version: 'unknown',
+    })).toEqual({
+      title: 'Host Console is not available on this node',
+      body: 'Peer does not advertise this capability. Upgrade the node to use this feature.',
+    });
+  });
+
+  it('treats an undefined mode as the generic proxy fallback', () => {
+    expect(resolveHostConsoleLockMessage({
+      nodeMode: undefined,
+      nodeName: 'Peer',
+      version: null,
+    })).toEqual({
+      title: 'Host Console is not available on this node',
+      body: 'Peer does not advertise this capability. Upgrade the node to use this feature.',
+    });
+  });
+});

frontend/src/lib/routing/hostConsoleCapability.ts

@@ -2,6 +2,8 @@ import {
   HOST_CONSOLE_CAPABILITY,
   HOST_CONSOLE_COMMUNITY_CAPABILITY,
 } from '@/lib/capabilities';
+import type { NodeMode } from '@/context/NodeContext';
+import { formatVersion } from '@/lib/version';
 
 export type HostConsoleCapabilityState = 'loading' | 'allowed' | 'locked';
 
@@ -47,3 +49,42 @@ export function resolveHostConsoleCapability(
   if (!licenseReady) return 'loading';
   return isPaid ? 'allowed' : 'locked';
 }
+
+export interface HostConsoleLockMessageInput {
+  /** Active node mode. Pilot Agent tunnels do not carry Host Console yet. */
+  nodeMode: NodeMode | undefined;
+  nodeName: string;
+  version: string | null | undefined;
+}
+
+/**
+ * Lock-card copy for a node whose Host Console capability is missing.
+ *
+ * Pilot Agent nodes cannot advertise the Host Console capability because the
+ * interactive console path is not wired through the Pilot tunnel, so an
+ * upgrade would not enable it. They get transport-specific copy instead of the
+ * generic "upgrade the node" instruction. Every other mode (proxy remote or
+ * missing metadata) keeps the generic upgrade message: version-aware when a
+ * real version is present, otherwise a no-capability hint.
+ */
+export function resolveHostConsoleLockMessage(
+  input: HostConsoleLockMessageInput,
+): { title: string; body: string } {
+  const { nodeMode, nodeName, version } = input;
+
+  if (nodeMode === 'pilot_agent') {
+    return {
+      title: 'Host Console is not available through Pilot Agent yet',
+      body: 'Host Console is currently available on the local node and Distributed API Proxy remotes.',
+    };
+  }
+
+  const formatted = formatVersion(version);
+  const versionHint = formatted
+    ? `${nodeName} is running ${formatted}.`
+    : `${nodeName} does not advertise this capability.`;
+  return {
+    title: 'Host Console is not available on this node',
+    body: `${versionHint} Upgrade the node to use this feature.`,
+  };
+}